OAuth

OAuth is a protocol that enables a resource owner, such as a user, to allow a third party access to a protected resource without sharing a user name or password. Instead, an access token is used to grant access to the protected resource. For Eclipse Amlen, it enables a client application to connect to the Eclipse Amlen server without sharing the user name or password with Eclipse Amlen. Eclipse Amlen supports OAuth 2.0.

With the OAuth protocol, a client application can be granted access to a resource server without entering a user name and password to access that server. Instead, the client application is authenticated by a trusted server that is known as an authorization server. The authorization server returns an access token to the client application so that the client application can connect to the resource server without entering a user name or password.

For example, a client application, such as a photo-printing service, can be granted access to photos that are stored on a protected server, without the user name and password for that server. The photo-printing service requests that user authenticate with an authorization server. The authorization server issues an access token, which is used by the photo-printing service to request access to the photos. When the access token is accepted by the protected server, the photo-printing service can access the photos to print them.

The following diagram shows the flow to authenticate a client to connect to Eclipse Amlen by using OAuth:
Figure 1. OAuth flow to authenticate a client to connect to Eclipse Amlen
A diagram that shows the OAuth flow to authenticate a client to connect to Eclipse Amlen
  1. The Eclipse Amlen client logs on to the client application server to request authorization to connect to Eclipse Amlen.
  2. The client application server requests authorization from the authorization server.
  3. The authorization server connects to the LDAP server to authenticate the user.
  4. The authorization server creates an authorization token and returns it to the Eclipse Amlen client. The authorization token is in JSON format and includes the following data:
     {"expires_in":86400, "refresh_token":"18927670-R-2v8e8ycA419RaaVWY9Xz4APp", 
"access_token":"18926970-A-nMnSHDqg8Fsunm6Qx1cF1APp"}
  5. The Eclipse Amlen client connects to Eclipse Amlen with the user name IMA_OAUTH_ACCESS_TOKEN and the authorization token as a password. The Eclipse Amlen client must send the complete authorization token, in JSON format, including the "expires_in", "refresh_token", and "access_token" data fields, as a password.
  6. Eclipse Amlen connects to the authorization server to validate the access token. The name of the access token and the value specified by the AuthKey parameter in the OAuth profile must match. If the token is validated, the client can connect to Eclipse Amlen.

    The URL to use to connect to the authorization server to validate the access token is specified by the ResourceURL parameter in an OAuth profile.

  7. If any connection or messaging policies on Eclipse Amlen require authorization that is based on group ID, Eclipse Amlen must first retrieve the user name that is associated with the access token. The user name must be retrieved from the authorization server. You can configure the authorization server to return a comma-separated list of groups to which the user belongs, as well as the user name. Alternatively, you can use the user name that is returned from the authorization server to retrieve group ID information from an LDAP server.

    The URL to use to connect to the authorization server to retrieve the user information is specified by the UserInfoURL parameter in an OAuth profile. The user ID is returned as a JSON object. The authorization server can also return the group ID in the JSON object. The names of the user ID and group ID are specified by the UserInfoKey and GroupInfoKey parameters respectively in the OAuth profile.

    If the authorization server is configured to return the user ID and group ID in the response to the authorization request, the values specified in the ResourceURL and UserInfoURL parameters in the OAuth profile must be the same.

    For more information about configuring OAuth, see Configuring OAuth.

  8. If Eclipse Amlen is not configured to retrieve the group name from the authorization server, then the user ID that is returned from the authorization server can be used by Eclipse Amlen to connect to an external LDAP server to retrieve the name of the group to which the user belongs.
To configure Eclipse Amlen to use OAuth, you must complete the following steps:
  1. Configure the client application to use user name and password authentication where the user name is IMA_OAUTH_ACCESS_TOKEN, and the password is the authorization token.
  2. Register the client application with the authorization server.
    The registered application is assigned a client ID and a client secret. In WebSphere® Application Server, this information is stored in <AppServer_cell_directory>/oauth20/base_clients.xml: 
    <client id="MessageGatewayExampleClient" component="MessageGatewayProvider" secret="Secret"  displayname="Message Gateway Client" redirect="https://192.0.2.1:16102" enabled="true">
</client>
  3. Configure Eclipse Amlen for OAuth:
    1. Create an OAuth profile that defines the access token name, and the authorization server URL to validate the token. Optionally, the OAuth profile can define the authorization server URL to retrieve user information.
    2. Associate the OAuth profile with a security profile.
    For more information about how to configure OAuth for Eclipse Amlen, see Configuring OAuth.