Skip to content

Api

Jump to bottom Edit New page
jricher edited this page Apr 26, 2013 · 11 revisions

The MITREid Connect server has a robust RESTful API that is used to manage various aspects of the server's configuration. In fact, the administration UI is really just a JavaScript application that uses this RESTful API to do its job.

The API may be accessed through an active web session within the application (ie, any JavaScript running on the server itself) or through authorizing a client application through OAuth.

Clients

Manages all registered clients on the system, both statically and dynamically registered.

Endpoint: /api/clients

GET /api/clients

Requires ROLE_USER or ROLE_ADMIN access.

Get a list of all clients on the system, returns results in application/json.

[

    {
        "id": 1,
        "clientId": "client",
        "clientSecret": "secret",
        "redirectUris": [
            "http://localhost/",
            "http://localhost:8080/"
        ],
        "clientName": "Test Client",
        "clientUri": null,
        "logoUri": null,
        "contacts": [ ],
        "tosUri": null,
        "tokenEndpointAuthMethod": null,
        "scope": [
            "phone",
            "openid",
            "offline_access",
            "address",
            "email",
            "profile"
        ],
        "grantTypes": [
            "implicit",
            "authorization_code",
            "urn:ietf:params:oauth:grant_type:redelegate",
            "refresh_token"
        ],
        "responseTypes": [ ],
        "policyUri": null,
        "jwksUri": null,
        "applicationType": null,
        "sectorIdentifierUri": null,
        "subjectType": null,
        "requestObjectSigningAlg": null,
        "userInfoSignedResponseAlg": null,
        "userInfoEncryptedResponseAlg": null,
        "userInfoEncryptedResponseEnc": null,
        "idTokenSignedResponseAlg": null,
        "idTokenEncryptedResponseAlg": null,
        "idTokenEncryptedResponseEnc": null,
        "defaultMaxAge": null,
        "requireAuthTime": null,
        "defaultACRvalues": [ ],
        "initiateLoginUri": null,
        "postLogoutRedirectUri": null,
        "requestUris": [ ],
        "authorities": [ ],
        "accessTokenValiditySeconds": 3600,
        "refreshTokenValiditySeconds": null,
        "resourceIds": [ ],
        "clientDescription": null,
        "reuseRefreshToken": true,
        "dynamicallyRegistered": false,
        "allowIntrospection": true,
        "idTokenValiditySeconds": 600,
        "createdAt": null
    }

]

Note: This method will return different information depending on whether or not the authorized user is an administrator. A non-administrator will get a limited set of information back:

[

    {
        "id": 1,
        "clientId": "client",
        "clientName": "Test Client",
        "logoUri": null,
        "scope": [
            "phone",
            "openid",
            "offline_access",
            "address",
            "email",
            "profile"
        ],
        "clientDescription": null
    }
]

POST /api/clients

Requires ROLE_ADMIN access.

Create a new client on the system. Message body is an application/json object with all client parameters:

{
        "id": 1,
        "clientId": "client",
        "clientSecret": "secret",
        "redirectUris": [
            "http://localhost/",
            "http://localhost:8080/"
        ],
        "clientName": "Test Client",
        "clientUri": null,
        "logoUri": null,
        "contacts": [ ],
        "tosUri": null,
        "tokenEndpointAuthMethod": null,
        "scope": [
            "phone",
            "openid",
            "offline_access",
            "address",
            "email",
            "profile"
        ],
        "grantTypes": [
            "implicit",
            "authorization_code",
            "urn:ietf:params:oauth:grant_type:redelegate",
            "refresh_token"
        ],
        "responseTypes": [ ],
        "policyUri": null,
        "jwksUri": null,
        "applicationType": null,
        "sectorIdentifierUri": null,
        "subjectType": null,
        "requestObjectSigningAlg": null,
        "userInfoSignedResponseAlg": null,
        "userInfoEncryptedResponseAlg": null,
        "userInfoEncryptedResponseEnc": null,
        "idTokenSignedResponseAlg": null,
        "idTokenEncryptedResponseAlg": null,
        "idTokenEncryptedResponseEnc": null,
        "defaultMaxAge": null,
        "requireAuthTime": null,
        "defaultACRvalues": [ ],
        "initiateLoginUri": null,
        "postLogoutRedirectUri": null,
        "requestUris": [ ],
        "authorities": [ ],
        "accessTokenValiditySeconds": 3600,
        "refreshTokenValiditySeconds": null,
        "resourceIds": [ ],
        "clientDescription": null,
        "reuseRefreshToken": true,
        "dynamicallyRegistered": false,
        "allowIntrospection": true,
        "idTokenValiditySeconds": 600,
        "createdAt": null
}

Any omitted values will be filled in with appropriate defaults in the following manner:

  • If clientId is empty, a new client id will be generated by the server
  • If clientSecret is empty and a field named generateSecret is sent and set to true, then a new client secret will be generated by the server
  • If scope is omitted or null, all system scopes marked as "default" will be assigned to the client

The server will return an updated copy of the object in application/json format as described under GET /api/clients/{id}.

GET /api/clients/{id}

Requires ROLE_USER or ROLE_ADMIN access.

Get information about a specific client identified by {id} in the url, in application/json format.

For example, the call to /api/clients/1 would return:

{
        "id": 1,
        "clientId": "client",
        "clientSecret": "secret",
        "redirectUris": [
            "http://localhost/",
            "http://localhost:8080/"
        ],
        "clientName": "Test Client",
        "clientUri": null,
        "logoUri": null,
        "contacts": [ ],
        "tosUri": null,
        "tokenEndpointAuthMethod": null,
        "scope": [
            "phone",
            "openid",
            "offline_access",
            "address",
            "email",
            "profile"
        ],
        "grantTypes": [
            "implicit",
            "authorization_code",
            "urn:ietf:params:oauth:grant_type:redelegate",
            "refresh_token"
        ],
        "responseTypes": [ ],
        "policyUri": null,
        "jwksUri": null,
        "applicationType": null,
        "sectorIdentifierUri": null,
        "subjectType": null,
        "requestObjectSigningAlg": null,
        "userInfoSignedResponseAlg": null,
        "userInfoEncryptedResponseAlg": null,
        "userInfoEncryptedResponseEnc": null,
        "idTokenSignedResponseAlg": null,
        "idTokenEncryptedResponseAlg": null,
        "idTokenEncryptedResponseEnc": null,
        "defaultMaxAge": null,
        "requireAuthTime": null,
        "defaultACRvalues": [ ],
        "initiateLoginUri": null,
        "postLogoutRedirectUri": null,
        "requestUris": [ ],
        "authorities": [ ],
        "accessTokenValiditySeconds": 3600,
        "refreshTokenValiditySeconds": null,
        "resourceIds": [ ],
        "clientDescription": null,
        "reuseRefreshToken": true,
        "dynamicallyRegistered": false,
        "allowIntrospection": true,
        "idTokenValiditySeconds": 600,
        "createdAt": null
}

Note: This method will return different information depending on whether or not the authorized user is an administrator. A non-administrator will get a limited set of information back:

{
        "id": 1,
        "clientId": "client",
        "clientName": "Test Client",
        "logoUri": null,
        "scope": [
            "phone",
            "openid",
            "offline_access",
            "address",
            "email",
            "profile"
        ],
        "clientDescription": null
}

PUT /api/clients/{id}

Requires ROLE_ADMIN access.

Update the information for the client identified by {id} in the URL. The request body must be application/json describing the entire client object:

{
        "id": 1,
        "clientId": "client",
        "clientSecret": "secret",
        "redirectUris": [
            "http://localhost/",
            "http://localhost:8080/"
        ],
        "clientName": "Test Client",
        "clientUri": null,
        "logoUri": null,
        "contacts": [ ],
        "tosUri": null,
        "tokenEndpointAuthMethod": null,
        "scope": [
            "phone",
            "openid",
            "offline_access",
            "address",
            "email",
            "profile"
        ],
        "grantTypes": [
            "implicit",
            "authorization_code",
            "urn:ietf:params:oauth:grant_type:redelegate",
            "refresh_token"
        ],
        "responseTypes": [ ],
        "policyUri": null,
        "jwksUri": null,
        "applicationType": null,
        "sectorIdentifierUri": null,
        "subjectType": null,
        "requestObjectSigningAlg": null,
        "userInfoSignedResponseAlg": null,
        "userInfoEncryptedResponseAlg": null,
        "userInfoEncryptedResponseEnc": null,
        "idTokenSignedResponseAlg": null,
        "idTokenEncryptedResponseAlg": null,
        "idTokenEncryptedResponseEnc": null,
        "defaultMaxAge": null,
        "requireAuthTime": null,
        "defaultACRvalues": [ ],
        "initiateLoginUri": null,
        "postLogoutRedirectUri": null,
        "requestUris": [ ],
        "authorities": [ ],
        "accessTokenValiditySeconds": 3600,
        "refreshTokenValiditySeconds": null,
        "resourceIds": [ ],
        "clientDescription": null,
        "reuseRefreshToken": true,
        "dynamicallyRegistered": false,
        "allowIntrospection": true,
        "idTokenValiditySeconds": 600,
        "createdAt": null
}

Any omitted values will be filled in with appropriate defaults in the following manner:

  • If clientId is empty, a new client id will be generated by the server
  • If clientSecret is empty and a field named generateSecret is sent and set to true, then a new client secret will be generated by the server
  • If scope is omitted or null, all system scopes marked as "default" will be assigned to the client

The server will return an updated copy of the object in application/json format as described under GET /api/clients/{id} on success.

DELETE /api/clients/{id}

Requires ROLE_ADMIN access.

Deletes the client with the {id} in the URL.

Returns HTTP 200 with an empty page on success.

Whitelists

Whitelist entries allow an administrator to specify which clients will not cause a prompt a user for authorization under certain circumstances, such as a subset of the scopes for that client.

Endpoint: /api/whitelist

GET /api/whitelist

Requires ROLE_USER or ROLE_ADMIN access.

Get a list of all whitelists on the system, returns results in application/json.

[

    {
        "id": 1,
        "creatorUserId": "jricher",
        "clientId": "client",
        "allowedScopes": [
            "email",
            "openid",
            "profile"
        ]
    }

]

POST /api/whitelist

Requires ROLE_ADMIN access.

Create a new whitelist on the system. Message body is an application/json object with all information:

{
        "id": 1,
        "creatorUserId": "jricher",
        "clientId": "client",
        "allowedScopes": [
            "email",
            "openid",
            "profile"
        ]
}

The server will return an updated copy of the object in application/json format as described under GET /api/whitelist/{id} on success.

GET /api/whitelist/{id}

Requires ROLE_USER or ROLE_ADMIN access.

Get information about a specific whitelist identified by {id} in the url, in application/json format.

For example, the call to /api/whitelist/1 would return:

{
        "id": 1,
        "creatorUserId": "jricher",
        "clientId": "client",
        "allowedScopes": [
            "email",
            "openid",
            "profile"
        ]
}

PUT /api/whitelist/{id}

Requires ROLE_ADMIN access.

Update the information for the whitelist identified by {id} in the URL. The request body must be application/json describing the entire whitelist object:

{
        "id": 1,
        "creatorUserId": "jricher",
        "clientId": "client",
        "allowedScopes": [
            "email",
            "openid",
            "profile"
        ]
}

The server will return an updated copy of the object in application/json format as described under GET /api/whitelist/{id} on success.

DELETE /api/whitelist/{id}

Requires ROLE_ADMIN access.

Deletes the whitelist with the {id} in the URL.

Returns HTTP 200 with an empty page on success.

Blacklists

System Scopes

User Site Approvals

Software is available under the Apache 2.0 license. Documentation available under the Creative Commons 3.0 By-NC license.

Links

Development

Clients

Protected Resources

Servers

Clone this wiki locally