Authentication URL user registry

You can use an Authentication URL user registry to specify a REST authentication service to manage user authentication, and to optionally provide additional metadata to be embedded in the token.

This support can optionally enable any of the following:
  • Providing the authenticated credential to IBM® API Connect. For example, the user logs-in with user name: spoon, and password: fork. When the user is authenticated, the credential becomes cn=spoon,o=eatery. The credential is kept in the OAuth access_token to represent the user.
  • Providing metadata support. Allow extra metadata to be stored in the access_token.
  • Overriding the scope that the application receives after a successful OAuth protocol processing. By responding with a specific header, the Authentication URL endpoint can replace the scope value that the application receives. For example, you can provide a specific resource owner an account number within the scope header response for use in future processing steps.

When you call the Authentication URL user registry, the API Connect gateway sends a GET request with HTTP headers and then processes any HTTP response from the URL. For authentication, a REST authentication service is expected at the Authentication URL.

The following response from the REST authentication service indicates that user authentication is successful and that API Connect will use cn=spoon,o=eatery as the user identity.
HTTP/1.1 200 OK
Server: example.org
X-API-Authenticated-Credential: cn=spoon,o=eatery

For information on how to configure a User Security policy in an API assembly for use with an Authentication URL user registry, see User Security policy.

For an example of an OAuth provider configuration that uses an Authentication URL user registry, see Example - using multiple OAuth policies in an OAuth provider assembly.

API Connect considers any non-200 HTTP response code a failed user authentication attempt.

When an Authentication URL user registry is invoked, two HTTP response headers are available that include metadata in the access token or the response payload that contains the access token. For more information, see OAuth external URL and authentication URL. The two metadata response headers are: 
API-OAUTH-METADATA-FOR-ACCESSTOKEN
API-OAUTH-METADATA-FOR-PAYLOAD
When an Authentication URL is invoked, an HTTP response header is available to override the requested scope from the application. For more information, see Scope. The response header is: 
x-selected-scope
Diagram to illustrate how the authentication URL works
If you are using the DataPower® API Gateway rather than the DataPower Gateway (v5 compatible), this diagram is provided for guidance only and is not fully accurate for this release.