OAuth 2.0 message attributes

This section describes the message attributes that are available in the API Gateway OAuth server and OAuth client filters.

OAuth 2.0 server message attributes

Most of the OAuth 2.0 server policy filters in the API Gateway generate message attributes that can be queried further using the API Gateway selector syntax. For example, the message attributes generated by the OAuth server filters include the following:

accesstoken
accesstoken.authn
authzcode
authentication.subject.id
oauth.client.details
scope attributes

For more details on selectors, see the API Gateway Policy Developer Guide.

accesstoken methods

The following methods are available to call on the accesstoken message attribute:

${accesstoken.getValue()}
${accesstoken.getExpiration()}
${accesstoken.getExpiresIn()}
${accesstoken.isExpired()}
${accesstoken.getTokenType()}
${accesstoken.getRefreshToken()}
${accesstoken.getOAuth2RefreshToken().getValue()}
${accesstoken.getOAuth2RefreshToken().getExpiration()}
${accesstoken.getOAuth2RefreshToken().getExpiresIn()}
${accesstoken.getOAuth2RefreshToken().hasExpired()}
${accesstoken.hasRefresh()}
${accesstoken.getScope()}
${accesstoken.getAdditionalInformation()}

The following example shows output from querying each of the accesstoken methods:

so0HlJYASrnXqn2fL2VWgiunaLfSBhWv6W7JMbmOa131HoQzZB1rNJ
Fri Oct 05 17:16:54 IST 2012
3599
false
Bearer
xif9oNHi83N4ETQLQxmSGoqfu9dKcRcFmBkxTkbc6yHDfK
xif9oNHi83N4ETQLQxmSGoqfu9dKcRcFmBkxTkbc6yHDfK
Sat Oct 06 04:16:54 IST 2012
43199
false
true
https://localhost:8090/auth/userinfo.email
{department=engineering}

accesstoken.authn methods

The following methods are available to call on the accesstoken.authn message attribute:

${accesstoken.authn.getUserAuthentication()}
${accesstoken.authn.getAuthorizationRequest().getScope()}
${accesstoken.authn.getAuthorizationRequest().getClientId()}
${accesstoken.authn.getAuthorizationRequest().getState()}
${accesstoken.authn.getAuthorizationRequest().getRedirectUri()}
${accesstoken.authn.getAuthorizationRequest().getParameters()}

The following example shows output from querying each of the accesstoken.authn methods:

admin
[https://localhost:8090/auth/userinfo.email]
SampleConfidentialApp
343dqak32ksla
https://localhost/oauth_callback
{client_secret=6808d4b6-ef09-4b0d-8f28-3b05da9c48ec, 
  scope=https://localhost:8090/auth/userinfo.email, grant_type=authorization_code, 
  redirect_uri=https://localhost/oauth_callback, state=null, 
  code=FOT4nudbglQouujRl8oH3EOMzaOlQP, client_id=SampleConfidentialApp}

authzcode methods

The following methods are available to call on the authzcode message attribute:

${authzcode.getCode()}
${authzcode.getState()}
${authzcode.getApplicationName()}
${authzcode.getExpiration()}
${authzcode.getExpiresIn()}
${authzcode.getRedirectURI()}
${authzcode.getScopes()}
${authzcode.getUserIdentity()}
${authzcode.getAdditionalInformation()}

The following example shows output from querying each of the authzcode methods:

F8aHby7zctNRknmWlp3voe61H20Md1
sds12dsd3343ddsd
SampleConfidentialApp
Fri Oct 05 15:47:39 IST 2012
599 (expiry in secs)
https://localhost/oauth_callback
[https://localhost:8090/auth/userinfo.email]
admin
{costunit=hr}

oauth.client.details methods

The following methods are available to call on the oauth.client.details message attribute:

${oauth.client.details.getClientType()}
${oauth.client.details.getApplication()}
${oauth.client.details.getBase64EncodedCert()}
${oauth.client.details.getX509Cert()}
${oauth.client.details.getName()}
${oauth.client.details.getDescription()}
${oauth.client.details.getLogo()}
${oauth.client.details.getApplicationID()}
${oauth.client.details.getContactPhone()}
${oauth.client.details.getContactEmail()}
${oauth.client.details.getClientID()}
${oauth.client.details.getClientSecret()}
${oauth.client.details.getRedirectURLs()}
${oauth.client.details.getScopes()}
${oauth.client.details.getDefaultScopes()}
${oauth.client.details.isEnabled()}

The following example shows output from querying each of the oauth.client.details methods:

confidential
com.vordel.common.apiserver.model.Application@126c334d
-----BEGIN CERTIFICATE-----MIICwzCCAasCBgE6HBsdpzANBg ......END CERTIFICATE
CN=Change this for production
Demo App
Demo App Desc
https://localhost:80/images/logo.png
dce2efc8-e9d4-4976-8a0f-3d2a2ec3a26d
000-111-222-333
temp@axway.com
d0e8952f-cefe-18e1-b2bf-8accdc456933
796501dd-7df5-4a94-a111-146c7bbab22a
[https://localhost:8088/redirect]
[com.vordel.common.apiserver.discovery.model.OAuthAppScope@6a25ce50]
[com.vordel.common.apiserver.discovery.model.OAuthAppScope@6a25ce50, 
  com.vordel.common.apiserver.discovery.model.OAuthAppScope@580c1ca1]
true

Example of querying a message attribute

If you add additional access token parameters to the OAuth Access Token Info filter, you can return a lot of additional information about the token. For example:

{
  "audience" :"SampleConfidentialApp",
  "user_id" :"admin",
  "scope" :"https://localhost:8090/auth/userinfo.email",
  "expires_in" :3567,
  "Access Token Expiry Date" :"Wed Aug 15 11:19:19 IST 2012",
  "Authentication parameters" :"{username=admin, 
client_secret=6808d4b6-ef09-4b0d-8f28-3b05da9c48ec, 
scope=https://localhost:8090/auth/userinfo.email, grant_type=password, 
redirect_uri=null, state=null, client_id=SampleConfidentialApp, 
password=xxxxxxxx}",
  "Access Token Type:" :"Bearer"

You also have the added flexibility to add extra name/value pair settings to access tokens upon generation. The OAuth 2.0 access token generation filters provide an option to store additional parameters for an access token. For example, if you add the name/value pair Department/Engineering to the Client Credentials filter:

Adding Additional OAuth 2.0 Access Token Parameters

You can then update the Access Token Info filter to add a name/value pair using a selector to get the following value:

Department/${accesstoken.getAdditionalInformation().get("Department")}

For example:

Retrieving Parameters from OAuth 2.0 Access Token

Then the JSON response is as follows:

{
  "audience" :"SampleConfidentialApp",
  "user_id" :"SampleConfidentialApp",
  "scope" :"https://localhost:8090/auth/userinfo.email",
  "expires_in" :3583,
  "Access Token Type:" :"Bearer",
  "Authentication parameters" :"{client_secret=6808d4b6-ef09-4b0d-8f28-3b05da9c48ec, 
scope=https://localhost:8090/auth/userinfo.email, grant_type=client_credentials, 
redirect_uri=null, state=null, client_id=SampleConfidentialApp}",
  "Department" :"Engineering",
  "Access Token Expiry Date" :"Wed Aug 15 12:10:57 IST 2012"

You can also use API Gateway selector syntax when storing additional information with the token. For more details on selectors, see the API Gateway Policy Developer Guide.

OAuth scope attributes

In addition, the following message attributes are used by the OAuth filters to manage OAuth scopes. The scopes are stored as a set of strings (for example, resource.READ and resource.WRITE):

scopes.in.token
Stores the OAuth scopes that have been sent in to the authorization server when requesting the access token.
scopes.for.token
Stores the OAuth scopes that have been granted for the access token request.
scopes.required
Used by the Validate Access Token filter only. If there is a failure accessing an OAuth resource due to incorrect scopes in the access token, an insufficent_scope exception is sent back in the WWW-Authenticate header. When Get scopes by calling a policy is set, the configured policy can set the scopes.required message attribute. This enables the OAuth resource server to properly interact with client applications and provide useful error response messages. For example:

WWW-Authenticate  Bearer realm="DefaultRealm",
error="insufficient_scope",
error_description="scope(s) associated with access token are not valid to access this resource", 
scope="Scopes must match All of these scopes:https://localhost:8090/auth/user.photos 
 https://localhost:8090/auth/userinfo.email"

OAuth SAML bearer attributes

The message attribute oauth.saml.doc is set on the message whiteboard by the Access Token using SAML Assertion filter. This is a W3C DOM document view of the SAML bearer assertion that API Gateway receives from an OAuth client application. The document in this form can be verified by other filters, but in an OAuth context the XML Signature Verification is typically used. For more information, see the XML Signature Verification filter in the API Gateway Policy Developer Guide.

OAuth 2.0 client message attributes

The OAuth 2.0 client policy filters in API Gateway generate message attributes that can be queried further using the API Gateway selector syntax. The message attributes generated by the OAuth 2.0 client filters include the following:

oauth.client.accesstoken
oauth.client.application

For more details on selectors, see the API Gateway Policy Developer Guide.

oauth.client.accesstoken methods

The following methods are available to call on the oauth.client.accesstoken message attribute:

${oauth.client.accesstoken.getAuthentication()}
${oauth.client.accesstoken.getClientId()}
${oauth.client.accesstoken.getAccessToken()}
${oauth.client.accesstoken.getCreated()}
${oauth.client.accesstoken.isExpired()}
${oauth.client.accesstoken.hasRefresh()}
${oauth.client.accesstoken.getRefreshToken()}
${oauth.client.accesstoken.getExpiresIn()}
${oauth.client.accesstoken.getExpiryDate()}
${oauth.client.accesstoken.getParams()}
${oauth.client.accesstoken.getTokenType()}

The following example shows output from querying each of the oauth.client.accesstoken methods:

regadmin
 ClientConfidentialApp
 SIDnxbYabJwRZpKexUx6R3dTEwKOj0afQo7sr2DrDYuJaVCAb9xvPBk
 Thu Mar 06 12:34:44 GMT 2014
 false
 true
 GokdAuu706ydZtNkl92UEPmnJRNmVBJPiPVGGrEwXKz5Uh
 3599
 Thu Mar 06 13:34:43 GMT 2014
 {state=9a388d14-a0e9-4b32-9003-e322c93279dd, scope=resource.WRITE}

oauth.client.application methods

This attribute represents the provider profile selected in the filter. It contains the provider details, such as token and authorization endpoints, and the token store, as well as the specifics of the client application including the client ID and secret. The following methods are available to call on the oauth.client.application message attribute:

${oauth.client.application.getTokenURL()}
${oauth.client.application.getAuthentication()}
${oauth.client.application.getProviderName()}
${oauth.client.application.getAppName()}
${oauth.client.application.getClientID()}
${oauth.client.application.getFlow()}
${oauth.client.application.getClientSecret()}
${oauth.client.application.getExtraTokenRequestProps()}
${oauth.client.application.getScopes()}
${oauth.client.application.getLocationOfClientDetails()}
${oauth.client.application.getClientIdHeaderName()}
${oauth.client.application.getClientSecretHeaderName()}
${oauth.client.application.getTokenStore()}
${oauth.client.application.getToken()}
${oauth.client.application.getTokenFromStore()}
${oauth.client.application.getProvider()}

The following example shows output from querying each of the oauth.client.application methods:

https://127.0.0.1:8089/api/oauth/token
regadmin
API Gateway
Sample Client Authzcode App
ClientConfidentialApp
authorization_code
9cb76d80-1bc2-48d3-8d31-edeec0fddf6c
{}
[resource.WRITE]
QueryString
client_id
client_secret
an object of type com.vordel.circuit.oauth.persistence.SynchronizedClientTokenStore
an object of type com.vordel.oauth.client.store.OAuth2ClientAccessToken
an object of type com.vordel.oauth.client.store.OAuth2ClientAccessToken
an object of type com.vordel.oauth.client.providers.BaseOAuth2Provider