Skip to end of metadata
Go to start of metadata

Starting with OpenAM 10, OpenAM includes the OAuth 2.0 authentication module that you can configure to communicate with OAuth 2.0 providers such as Facebook, Google, MSN, and others. To configure the module, see the Hints For the OAuth 2.0 Authentication Module in the OpenAM Admin Guide. You need to have the OAuth 2.0 client ID and client secret for your application when configuring the module, as well as some information about how to communicate with the OAuth 2.0 provider of your choice, as the module handles interaction with the OAuth 2.0 provider on your application's behalf.


How does the module work


The module works according to the OAuth 2.0 Authorization Protocol IETF draft specification

Here a simplified explanation on how it works:

  1. The user requests authentication using the OAuth 2.0 module
  2. OpenAM sends a request to the Authorization Service at the OAuth 2.0 Provider using a redirect through the user-agent (e.g. the browser).
    The request contains the client_id, redirect_uri, and scope configured for the authentication module.
  3. On receiving the request, the OAuth 2.0 Provider establishes whether the user grants or denies access to the request from OpenAM.
    If the user is not already authenticated with the OAuth 2.0 Provider, the OAuth 2.0 provider authenticates the user as part of this step.
  4. If the user grants access to the request from OpenAM, the OAuth 2.0 Provider sends an authorization_code to OpenAM via a redirect through the user-agent (browser).
  5. OpenAM requests an access token from the OAuth 2.0 Provider using the client_id, client_secret, and authorization_code received.
    The OAuth 2.0 provider validates the credentials and the authorization code, and returns an access token to OpenAM.
  6. OpenAM uses the access token to request user profile information, such as the email address and uses it to map to a local identity if the module was configured to do so.
  7. The authentication module returns success, and OpenAM provides an SSO Token.

How do I use it 


The Module can be used as any other OpenAM Authentication module, and therefore can be used as the authentication point when an application is being protected with a Policy Agent or SDK. The module can also be part of an authentication service or chain.
Here an example on how it works when used in conjunction with a Policy Agent that redirects to the OpenAM where the OAuth module has been configured.

  1. The user requests access to an application protected by OpenAM.
  2. The application detects the user has not been authenticated.
  3. The application sends the user to OpenAM to authenticate.
    In this case the application requests that the user to authenticate with the appropriate OAuth 2.0 authentication module, associated with a particular OAuth 2.0 Provider.
  4. OpenAM detects that the user is requesting authentication with the OAUth 2.0 authentication module.
    OpenAM first checks whether the user has been already authenticated. If not, then OpenAM initiates the OAuth 2.0 choreography by sending an authorization request via the user's browser to the OAuth 2.0 Provider's authorization service in the OAuth 2.0 Provider. The request contains the client_id, redirect_uri, and scope configured for the authentication module.
  5. The OAuth 2.0 Provider receives the request, and then begins to evaluate whether to authorize access.
  6. If the user has not yet authenticated to the OAuth 2.0 Provider, the provider requests the user's credentials.
  7. The user provides credentials to the OAuth 2.0 Provider.
  8. The OAuth 2.0 Provider requests the user's permission to grant or deny access to the request from OpenAM.
  9. If the user grants access, the OAuth 2.0 Provider sends OpenAM an authorization_code using a redirect through the user's browser.
  10. OpenAM receives the authorization_code, and issues an access token request directly to the OAuth 2.0 Provider.
    The request contains the client_id, client_secret, and the authorization_code.
  11. The OAuth 2.0 Provider validates the credentials and authorization_code from OpenAM.
    If everything is correct, the OAuth 2.0 Provider issues an access token directly to OpenAM.
  12. OpenAM uses the access token obtained to access user profile information, such as email, address, and name.
    This information is optional. You configure it through the authentication module configuration.
  13. The OAuth 2.0 Provider returns the attributes requested.
  14. OpenAM receives the information, and maps the information to the local user profile (depending on how you configured the authentication module).
    At this point OpenAM creates a local session, and adds an SSO Token to the request.
  15. OpenAM redirects the user-agent (browser) to the protected application.
  16. The protected application discovers that the request has been authenticated and provides the requested page.
    Optionally, an Authorization Request to validate the access to the page can be evaluated against the Policy Engine/Entitlements Service in OpenAM.
  17. Subsequent requests do not need to repeat the OAuth 2.0 sequence, as the user is already authenticated.

 

Features:

  1. The module offers the possibility to authenticate a user and map the account in different ways:
    1. Without any local identity in the OpenAM, however identifying the user by one of the attributes provided by the OAuth 2.0 provider
    2. Map the user to an "anonymous" account in the OpenAM
    3. Map the user to a local identity based on the attributes received from the OAuth 2.0 Provider
    4. Create an account on the fly on the OpenAM local user data store with the attributes received from the OAuth 2.0 Provider
  2. Global Logout as an option to also terminate the session with the OAuth 2.0 Provider
  3. Provide the access token and attributes obtained to trusted applications that use the OpenAM
  4. The Account Mapper, Attribute Mapper and Email gateway can be extended since they are implemented as plug-ins

End points for popular OAuth 2.0 Providers

Facebook

Authorization Endpoint URL: https://www.facebook.com/dialog/oauth
Access Token Endpoint URL: https://graph.facebook.com/oauth/access_token
User Profile Service URL: https://graph.facebook.com/me
OAuth 2.0 Provider logout service: http://www.facebook.com/logout.php

Google

1Authorization Endpoint URL: https://accounts.google.com/o/oauth2/auth
2Access Token Endpoint URL: https://accounts.google.com/o/oauth2/token
User Profile Service URL: https://www.googleapis.com/oauth2/v1/userinfo
OAuth 2.0 Provider logout service: https://mail.google.com/mail/?logout

1: In OpenAM 10.0.0 you might need to add the url parameter response_type=code.  OpenAM 10.1.0 Xpress does not require it
2: In OpenAM 10.0.0 you would need to add the url parameter grant_type=authorization_code. OpenAM 10.1.0 Xpress does not require it

MSN

1Authorization Endpoint URL: https://login.live.com/oauth20_authorize.srf
2Access Token Endpoint URL: https://login.live.com/oauth20_token.srf
User Profile Service URL: https://apis.live.net/v5.0/me
OAuth 2.0 Provider logout service: http://oauth.live.com/logout

1: In OpenAM 10.0.0 you might need to add the url parameter response_type=code. OpenAM 10.1.0 Xpress does not require it
2: In OpenAM 10.0.0 you would need to add the url parameter grant_type=authorization_code. OpenAM 10.1.0 Xpress does not require it

OpenAM OAuth 2.0 Provider (Available in OpenAM 10.1 Xpress)

Authorization Endpoint URL: https://your.openam.server/deployment_descriptor/oauth2/authorize
Access Token Endpoint URL: https://your.openam.server/deployment_descriptor/oauth2/access_token
User Profile Service URL: https://your.openam.server/deployment_descriptor/oauth2/tokeninfo
OAuth 2.0 Provider logout service: https://your.openam.server/deployment_descriptor/UI/Logout

Note: The End points for the OpenAM OAuth 2.0 Provider could also contain some additional parameters, like realm=/realm_name. For more information about the Provider functionality visit this link

Additional information on how to configure the module

You can check the Administration Guide referred in this link and you can also download this draft document that shows how to configure for example the module with Facebook.

Temporary Demo

You can see an example on how the module can be used in this link .

The demo has 3 use cases:

  1. Authentication using Facebook, Google or MSN without creating an account in the OpenAM.
  2. Authentication using Facebook, Google or MSN and creation of an account on the fly without asking any question.
    You can delete the account by clicking to the "Delete my account" link
  3. Authentication using Facebook, Google or MSN and creation of an account but prompting to set a password for the new account and awaiting for an activation code by email to be able to use it.
    The new account can be used also using the form prompting for user and password.
    You can delete the account by clicking to the "Delete my account" link


Note: The demo will be on for a certain time.

You can watch a video here 

  • No labels