OAuth: Using the Grant Admin API

This document provides information about using the GrantAdminAPI, including:

Authentication with the OAuth Provider

To use the GrantAdminAPI, you must authenticate with the OAuth Provider. To do this, you can use any one of these options:

  1. Log in by providing the email address and password of the user registered in Community Manager.
  2. Log in by providing the username/password of the LDAP domain (or any other domain that supports login with credentials provided by user). This can also be considered SSO login.
  3. SSO login by letting the user be redirected to the authentication domain site (just like the end-user authentication in 3-legged grant types).

Option 1 or option 2 are the most common scenarios.

Below are the request/response formats for all three use cases:

Use case 1: Log in by providing email address and password of the user registered in Community Manager

Operation: POST /oauth/login.

Request

Header Description
URL [oauth-provider-host]/oauth/login
Action POST
Request Headers

Content-Type: application/x-www-form-urlencoded

Accept: application/json

Request Payload

identity_email=[EMAIL]&secret_password=[PASSWORD]&Domain=siteusers

Response

  • The response includes a cookie that will be used for subsequent requests. For non-browser scenarios, the application must save this cookie and include it in every request. The cookie name includes the OAuth Provider name. Cookie name: OAuthToken_{OAuthProviderName}.
  • The response includes the UserName and DomainName of the user. Example: { "DomainName" : "Local Domain", "UserName" : "Rep1" }

Use case 2: Log in by providing the username/password of the LDAP domain user or OpenID Connect Relying Party Domain user

Operation: POST /oauth/login/ssoLogin.

Request

Header Description
URL [oauth-provider-host]/oauth/login/ssoLogin
Action POST
Request Headers

Content-Type: application/x-www-form-urlencoded

Accept: application/json

Request Parameters

Header Description
Domain: (Optional) Optional domain name parameter. If this parameter is missing, the platform uses the resource owner authentication domain.
identity_xxxx All parameters that start with identity_ are used as identity parameters. For LDAP and OpenID Connect Relying Party domains, use identity_username.
secret_xxxx All parameters that start with secret_ are used as secret parameters. For LDAP and OpenID Connect Relying Party domains, use secret_password.

Example

identity_username=[USERNAME]&secret_password=[PASSWORD]&Domain=[domain-name]

Response

  • The response includes a cookie that will be used for subsequent requests. For non-browser scenarios, the application must save this cookie and include it in every request. The cookie name includes the OAuth Provider name. Cookie name: OAuthToken_{OAuthProviderName}.
  • The response includes the UserName and DomainName of the user. For example: { "DomainName" : "ldap", "UserName" : "eng100" }

Use case 3: SSO login with user authenticating to the identity provider and OAuth provider authenticating to SSO token

This is just the same as the way the OAuth Provider authenticates the end users when asked for a new grant. This is mostly used for resource owners wanting to administer their grants.

Operation: POST /oauth/login/ssoLogin or GET /oauth/login/ssoLogin.

Request

Header Description
URL [oauth-provider-host]/oauth/login/ssoLogin
Action Both GET and POST are supported
Request Headers None required. However, if the domain uses a cookie to authenticate, include the cookie.

Request Payload

  • Any SSO token, if available, that the identity provider domain can use.
  • Domain=[domain-name] (Optional).

Response

The response is an html page that redirects the user to the identity provider to log in, and which then redirects the user back to the OAuth provider. The OAuth provider authenticates based on the SSO token, and then sets up the cookie as well as returning the JSON response with the authenticated user details.

Example: JSON response after redirects are done

{ "DomainName" : "OpenAM", "UserName" : "eng100" }

Renew Token

The OAuthToken cookie that is set up by the above login/ssologin API calls is valid for only 10 minutes. Before the token expires, you can renew it for another 10 minutes or make another login API call.

To renew the OAuthToken, use the below API.

Operation: POST /oauth/login/renewToken or GET /oauth/login/ssoLogin.

Request

Header Description
URL [oauth-provider-host]/oauth/login/renewToken
Action Both GET and POST are supported
Request Headers

Content-Type: application/x-www-form-urlencoded

Accept: application/json
Request Headers None

Response

  • The response includes a cookie that will be used for subsequent requests. For non-browser scenarios, the application must save this cookie and include it in every request. The cookie name includes the OAuth Provider name. Cookie name: OAuthToken_{OAuthProviderName}.
  • The response includes the UserName and DomainName of the user.

Response Example

{ "DomainName" : "ldap", "UserName" : "eng100" }

Logout

Once the API calls are made, the logout API removes the OAuthToken cookie and forces users to log in again before invoking any protected API calls.

Operation: GET /oauth/login/logout.

Request

Header Description
URL [oauth-provider-host]/oauth/login/logout
Action GET
Request Headers Accept: application/json

Request Payload

None.

Response

  • The OAuthToken cookie is removed.
  • The response payload is empty.

Query for List of Grants

As part of grant administration, you can query for the list of grants in a specific state, such as active state or in progress state. Grants are protected and can only be seen by resource owners (their own grants), client administrators (grants issued to their clients) and provider administrators (all grants).

Using the login/ssoLogin API calls above, resource owners/client administrators/provider administrators can authenticate to the OAuth Provider. After authentication, you can invoke the below API to query for the list of grants available.

Operation: GET /oauth/admin/grants

Request

Header Description
URL [oauth-provider-host]/oauth/admin/grants
Action GET
Request Headers

Accept: application/xml (or application/json)

Cookie set up by the Authentication API

Request Query Parameters

All query parameters are optional. These query parameters restrict the data returned, and therefore act as a filter to query based on.

Header Description
GrantSetupStartDate Date when grant is set up (format: yyyy-MM-dd’T’HH:mm:ss) value in GMT timezone.
GrantSetupEndDate Date before grant is set up (format: yyyy-MM-dd’T’HH:mm:ss) value in GMT timezone.
ClientID client-id of the client to which grants are issued.
ResourceOwnerUID The unique ID of the resource owner, as set up with the OAuth provider. This can be simply the UID, or can be the DOMAIN\UID if multiple domains are used and the same UID exists in different domains. DOMAIN here is the Resource Owner authentication domain of the Provider.
GrantStatus The status of the grant. This parameter can be included multiple times to fetch the grants in different statuses. Valid values: Pending, Active, Rejected, Revoked, Expired, Cancelled (see OAuth Grant Status).
SortBy

Sort criteria for the return list. Default value: Last Modified date descending.

Possible values:

  • grant.modified.date: Last modified date Descending
  • grant.setup.date: Grant setup date Descending
  • grant.status: Grant Status Ascending alphabetically
  • grant.resource.owner: Resource Owner UID Ascending
  • grant.client: ClientID Ascending
StartIndex An index number indicating the starting point for the results to be returned. If not specified, results start at position 0, the first result.
Count The number of results to be returned, from the specified starting point. If not specified, all matching results are returned. Default: 100.

Response

The response is an RSS feed with one item for each grant. Each RSS item includes an extension object with the property name "Grant" with all the grant details. Below is an example payload. For each grant, you can get the GrantID from either the RSS item guid or by using the GrantID property of the RSS item extension property, Grant, as shown in the highlighted examples below. The GrantID will be useful in subsequent API calls to administer the grant.

JSON Example

{
  "channel": {
    "title": "Grants",
    "description": "",
    "item": [
      {
        "title": "",
        "guid": {
          "value": "5dbv239gl72l"
        },
        "pubDate": "Tue, 12 May 2015 06:21:34 -0700",
        "Grant": {
          "GrantID": "5dbv239gl72l",
          "GrantProvider": "Capital One OAuth Provider",
          "GrantType": "authorization_code",
          "OpenIdConnectGrant": false,
          "GrantStatus": "Pending",
          "GrantExpirationDateTime": 1432732894000,
          "GrantClient": {
            "ClientID": "open-88PPmUA46HgAdUTzmYJRsa6H"
          },
          "GrantClientRedirectUri": "http://developer.acmepaymentscorp.com/ui/apps/acmepaymentscorp/_VSPUvNSKEu9CFztvkjorQcg/resources/console/global/oauthclientredirect.html?dynamic=true",
          "GrantResourceScope": {
            "Resource": [
              {
                "Name": "READ"
              },
              {
                "Name": "scope"
              }
            ]
          },
          "GrantIssuedDateTime": 1431436894000,
          "GrantUpdatedDateTime": 1431436894000,
          "ResponseType": "code"
        }
      },
      {
        "title": "",
        "guid": {
          "value": "cds24vlc2a82"
        },
        "pubDate": "Tue, 12 May 2015 06:23:46 -0700",
        "Grant": {
          "GrantID": "cds24vlc2a82",
          "GrantProvider": "Capital One OAuth Provider",
          "GrantType": "authorization_code",
          "OpenIdConnectGrant": false,
          "GrantStatus": "Pending",
          "GrantExpirationDateTime": 1432733026000,
          "GrantClient": {
            "ClientID": "open-88PPmUA46HgAdUTzmYJRsa6H"
          },
          "GrantClientRedirectUri": "http://developer.acmepaymentscorp.com/ui/apps/acmepaymentscorp/_VSPUvNSKEu9CFztvkjorQcg/resources/console/global/oauthclientredirect.html?dynamic=true",
          "GrantResourceScope": {
            "Resource": [
              {
                "Name": "READ"
              },
              {
                "Name": "scope"
              }
            ]
          },
          "GrantIssuedDateTime": 1431437026000,
          "GrantUpdatedDateTime": 1431437026000,
          "ResponseType": "code"
        }
      }
    ]
  },
  "version": "1.0"
}

XML example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<rss 
  xmlns:ns2="http://soa.com/xsd/rss/1.0" 
  xmlns:ns3="http://soa.com/xsd/oauth/1.0" 
  xmlns:ns4="http://soa.com/binding/http" version="1.0">
  <channel>
    <title>Grants</title>
    <description></description>
    <item>
      <title></title>
      <guid>5dbv239gl72l</guid>
      <pubDate>Tue, 12 May 2015 06:21:34 -0700</pubDate>
      <ns3:Grant>
        <ns3:GrantID>5dbv239gl72l</ns3:GrantID>
        <ns3:GrantProvider>Capital One OAuth Provider</ns3:GrantProvider>
        <ns3:GrantType>authorization_code</ns3:GrantType>
        <ns3:OpenIdConnectGrant>false</ns3:OpenIdConnectGrant>
        <ns3:GrantStatus>Pending</ns3:GrantStatus>
        <ns3:GrantExpirationDateTime 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:dateTime">2015-05-27T13:21:34Z
        </ns3:GrantExpirationDateTime>
        <ns3:GrantClient>
          <ns3:ClientID>open-88PPmUA46HgAdUTzmYJRsa6H</ns3:ClientID>
        </ns3:GrantClient>
        <ns3:GrantClientRedirectUri>http://developer.acmepaymentscorp.com/ui/apps/acmepaymentscorp/_VSPUvNSKEu9CFztvkjorQcg/resources/console/global/oauthclientredirect.html?dynamic=true</ns3:GrantClientRedirectUri>
        <ns3:GrantResourceScope>
          <ns3:Resource>
            <ns3:Name>READ</ns3:Name>
          </ns3:Resource>
          <ns3:Resource>
            <ns3:Name>scope</ns3:Name>
          </ns3:Resource>
        </ns3:GrantResourceScope>
        <ns3:GrantIssuedDateTime 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:dateTime">2015-05-12T13:21:34Z
        </ns3:GrantIssuedDateTime>
        <ns3:GrantUpdatedDateTime 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:dateTime">2015-05-12T13:21:34Z
        </ns3:GrantUpdatedDateTime>
        <ns3:ResponseType>code</ns3:ResponseType>
      </ns3:Grant>
    </item>
    <item>
      <title></title>
      <guid>cds24vlc2a82</guid>
      <pubDate>Tue, 12 May 2015 06:23:46 -0700</pubDate>
      <ns3:Grant>
        <ns3:GrantID>cds24vlc2a82</ns3:GrantID>
        <ns3:GrantProvider>Capital One OAuth Provider</ns3:GrantProvider>
        <ns3:GrantType>authorization_code</ns3:GrantType>
        <ns3:OpenIdConnectGrant>false</ns3:OpenIdConnectGrant>
        <ns3:GrantStatus>Pending</ns3:GrantStatus>
        <ns3:GrantExpirationDateTime 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:dateTime">2015-05-27T13:23:46Z
        </ns3:GrantExpirationDateTime>
        <ns3:GrantClient>
          <ns3:ClientID>open-88PPmUA46HgAdUTzmYJRsa6H</ns3:ClientID>
        </ns3:GrantClient>
        <ns3:GrantClientRedirectUri>http://developer.acmepaymentscorp.com/ui/apps/acmepaymentscorp/_VSPUvNSKEu9CFztvkjorQcg/resources/console/global/oauthclientredirect.html?dynamic=true</ns3:GrantClientRedirectUri>
        <ns3:GrantResourceScope>
          <ns3:Resource>
            <ns3:Name>READ</ns3:Name>
          </ns3:Resource>
          <ns3:Resource>
            <ns3:Name>scope</ns3:Name>
          </ns3:Resource>
        </ns3:GrantResourceScope>
        <ns3:GrantIssuedDateTime 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:dateTime">2015-05-12T13:23:46Z
        </ns3:GrantIssuedDateTime>
        <ns3:GrantUpdatedDateTime 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:dateTime">2015-05-12T13:23:46Z
        </ns3:GrantUpdatedDateTime>
        <ns3:ResponseType>code</ns3:ResponseType>
      </ns3:Grant>
    </item>
  </channel>
</rss>

Query for a Single Grant

To query for a single grant, use the URLs below to provide different information relating to the grant.

Returns all the information about the grant (operation: GET /oauth/admin/grants/{GrantID}):

[oauth-provider-host]/oauth/admin/grants/{GrantID}

Returns the client’s avatar image (operation: GET /oauth/admin/grants/{GrantID}/client/picture):

[oauth-provider-host]/oauth/admin/grants/{GrantID}/client/picture

Query for Clients List

To query for a list of client ids, use the below API. This API can only be invoked by Provider Administrators. Provider Administrators are site administrators in Community Manager.

Operation: GET /oauth/admin/clients.

Request

Header Description
URL [oauth-provider-host]/oauth/admin/clients
Action GET
Request Headers

Cookie set up by authentication APIs above.

Accept: application/json or application/xml

Request Query Parameters

Both parameters are optional. By default this API returns all client-ids with at least one grant in any state.

Header Description
IncludeClientsWithActiveGrants Default value true. Use false if you want to not include clients with active grants in the response list
IncludeClientsWithExpiredGrants Default value true. Use false if you want to not include clients with expired grants in the response list

If both the above query parameters are false, this API returns all client-ids with at least one grant in any state.

Response

The response is an RSS feed with one RSS item for each client ID. The only property available for each client is client-id. This API will be enhanced in future to include additional information about the Grant Client.

Example Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 
<rss xmlns:ns2="http://soa.com/xsd/rss/1.0" xmlns:ns3="http://soa.com/xsd/oauth/1.0" xmlns:ns4="http://soa.com/binding/http" version="1.0"> 
<channel> 
  <title>Clients</title> 
  <description>Clients either have active grants or expired grants with the Oauth Provider</description> 
  <item> 
     <title></title> 
     <guid>open-13MqsHYGZs7U75kJokqRv4vl</guid> 
     <ns3:GrantClient> 
      <ns3:ClientID>open-13MqsHYGZs7U75kJokqRv4vl</ns3:ClientID> 
     </ns3:GrantClient>
  </item> 
  <item> 
     <title></title>
     <guid>open-5ONp6iEvB9W1pAuemIyxnE9Q</guid> 
     <ns3:GrantClient> 
      <ns3:ClientID>open-5ONp6iEvB9W1pAuemIyxnE9Q</ns3:ClientID> 
     </ns3:GrantClient> 
  </item>  
</channel> 
</rss>

Performing an Action on a Grant

Grant administration is done by performing an action on a grant. For example, the action to revoke the grant could be done by the resource owner, client administrator, or provider administrator. There are reserved actions used by the provider as part of the grant issue process.

Custom actions could be introduced by customizing the workflow definition. For example, each action could be restricted based on the user’s roles and can result in changing the grant state.

Below are the API details to perform an action on a grant.

Operation: POST /oauth/admin/grants/{GrantID}/actions.

Note: for more information about revoking a grant, see OAuth: Revoking a Grant.

Request

Header Description
URL [oauth-provider-host]/oauth/admin/grants/{GrantID}/actions
Action POST
Request Headers

Content-Type: application/json

Accept: application/json

Cookie set up with any of the authentication APIs above.

Request Payload

{ 
   "Action" : "[ACTION]", 
   "Comment" : "[COMMENT]" 
}

Notes

The possible values for ACTION when using the out-of-box workflow definition are below. For a custom workflow, the list could be different based on the workflow definition. Default values are:

  • For Active grants, Actions allowed include:
    • resource.owner.revoked
    • resource.owner.cancelled
    • app.admin.cancelled
    • provider.admin.cancelled
  • For Revoked grants, Actions allowed include:
    • resource.owner.reinstated
    • resource.owner.cancelled
    • app.admin.cancelled
    • provider.admin.cancelled

In the above list, some actions have restrictions, as follows:

  • These actions are available to resource owner only:
    • resource.owned.revoked
    • resource.owner.reinstated
    • resource.owner.cancelled
  • This action is available to app administrator only:
    • app.admin.cancelled
  • This action is available to provider administrators only:
    • provider.admin.cancelled

Response

The Grant object is returned as JSON with the updated details.

Sample Response

{
    "GrantID": "hdoih0raf5q5",
    "GrantProvider": "Capital One OAuth Provider",
    "GrantType": "authorization_code",
    "OpenIdConnectGrant": false,
    "GrantStatus": "Cancelled",
    "GrantExpirationDateTime": 1431760908000,
    "GrantExpirationDateTimeInMillis": 1431760908000,
    "GrantClient": {
        "ClientID": "open-88PPmUA46HgAdUTzmYJRsa6H"
    },
    "GrantClientRedirectUri": "http://developer.acmepaymentscorp.com/ui/apps/acmepaymentscorp/_VSPUvNSKEu9CFztvkjorQcg/resources/console/global/oauthclientredirect.html?dynamic=true",
    "AuthorizationCode": "ywslZ8X1GTCzxvakpn-C1DzmczokZ99GlxFLOw",
    "AuthorizationCodeExpirationDateTime": 1430465508000,
    "ResourceOwnerUserInfo": {
        "DomainName": "OpenAM Connector",
        "UID": "eng100",
        "Attributes": {
            "Attribute": [
                {
                    "Name": "sub",
                    "Value": "eng100",
                    "Type": "string"
                }
            ]
        }
    },
    "GrantResourceScope": {
        "Resource": [
            {
                "Name": "READ"
            }
        ]
    },
    "GrantIssuedDateTime": 1430464879000,
    "GrantIssuedDateTimeInMillis": 1430464879000,
    "GrantUpdatedDateTime": 1434652015000,
    "GrantUpdatedDateTimeInMillis": 1434652015000,
    "ResponseType": "code"
}