Configuring the OAuth 2.0 Authentication module

Transcription

1 Configuring the OAuth 2.0 Authentication module Revision: 0.5 Date: 25/11/11 ForgeRock AS Philp Pedersens vei Lysaker Norway Copyright 2011 ForgeRock AS. All rights reserved Page 1 15/06/10

2 Disclaimer: Copyright 2011 ForgeRock AS. All rights reserved This document is provided "AS-IS" without warranty of any kind, either express or implied, including, but not limited to, the implied warranties of merchantability, fitness for a particular purpose, or non-infringement. This document could include inaccuracies or typographical errors. ForgeRock AS Proprietary Revisions Version Date Author Comments /10/11 Victor Ake Initial draft Distribution List Name Company Position Copyright 2011 ForgeRock AS. All rights reserved Page 2 15/06/10

3 Table of Contents Configuring the OAuth 2.0 Module for facebook...5 Use case 1: Pre-linked account and error message if the user does not have an account in the local user data store...6 Proxy URL...6 Account Mapper Configuration:...6 Attribute Mapper Configuration...7 Save Attributes in Session...7 Create account if it does not exist...7 Prompt for password setting and activation code...7 Map to anonymous user...7 OAuth 2.0 Provider logout service...7 Logout options...7 Use case 2: Authenticate the users from facebook in OpenAM even if there is no user profile in the local Data Store...7 Proxy URL...8 Account Mapper Configuration:...8 Attribute Mapper Configuration...8 Save Attributes in Session...9 Create account if it does not exist...9 Prompt for password setting and activation code...9 Map to anonymous user...9 OAuth 2.0 Provider logout service...9 Logout options...10 Use case 3: Authenticate the users from facebook in OpenAM and create users on the fly if they do not exist, without prompting anything else...10 Proxy URL...10 Account Mapper Configuration:...10 Attribute Mapper Configuration...10 Save Attributes in Session...11 Create account if it does not exist...11 Prompt for password setting and activation code...11 Map to anonymous user...11 OAuth 2.0 Provider logout service...11 Logout options...11 SMTP Options...11 Use case 4: Authenticate the users from facebook in OpenAM and create users on the fly, but this time prompt the users to set a password and create the account only if they provide an activation code...12 Proxy URL...12 Account Mapper Configuration:...12 Attribute Mapper Configuration...12 Save Attributes in Session attribute in OAuth2 Response...13 Create account if it does not exist...13 Prompt for password setting and activation code...13 Map to anonymous user...14 OAuth 2.0 Provider logout service...14 Logout options...14 Copyright 2011 ForgeRock AS. All rights reserved Page 3 15/06/10

4 SMTP Gateway implementation class...14 SMTP host...14 SMTP port...14 SMTP User Name...14 SMTP User Password...14 SMPT SSL Enabled...14 Use case 5: Authenticate the users from facebook in OpenAM and map to an anonymous account if accounts can not be mapped to a local user...14 Proxy URL...15 Account Mapper Configuration:...15 Attribute Mapper Configuration...15 Save Attributes in Session attribute in OAuth2 Response...15 Create account if it does not exist...16 Prompt for password setting and activation code...16 Map to anonymous user...16 Anonymous User...16 OAuth 2.0 Provider logout service...16 Logout options...16 SMTP Options...16 Copyright 2011 ForgeRock AS. All rights reserved Page 4 15/06/10

5 Configuring the OAuth 2.0 Module for facebook. If more than one instance of OpenAM are used in a Load Balanced environment, the Load balancer must provide sticky load balancing. 1. An account is needed in the OAuth 2.0 service to register the OpenAM as a web application. 2. Example for facebook: Go to and register the OpenAM as a web application. The app would look like: Illustration 1: Example of a Web application registered in Facebook Take special note of the APP Key and APP secret and pay attention to register the Site URL and site domain properly 3. In the example we assume the OpenAM URL is called (illustration 4) 4. Create an authentication module named facebook. 1. Login to the OpenAM web console 2. Go to the Access Control tab 3. Select the realm where you want to configure the module 4. Go to the Authentication tab and scroll down to the Module Instance section Copyright 2011 ForgeRock AS. All rights reserved Page 5 15/06/10

6 5. Click the New button 6. Give a name to the module, for example facebook and select OAuth 2.0 as the type 7. Click the OK button 8. A new module instance named facebook should appear in the list of module instances. 9. Click the module and configure accordingly. 10. In Cient Id specify the App/API Key from facebook (illustration 4) 11. In Client Secret specify the App Secret from your facebook application (illustration 4) 12.The rest of the parameters depend on the type of use case that is needed, but most of them should be OK by default. 5. There are several use cases that can be implemented with the module. For all the use cases, the authentication module will automatically save the OAuth 2.0 access token as a session attribute: OAuthToken: Contains the OAuth 2.0 Access Token Use case 1: Pre-linked account and error message if the user does not have an account in the local user data store We have users in the OpenAM User Data Store and the users have an attribute that contains the address registered in facebook, i.e. pre-linked account. Proxy URL Specify the URL of the OpenAM OAuth 2.0 Proxy. In the example it will be: Account Mapper Configuration: This is the attribute (or attributes) that will be used to search the users in the local user store. is the name of the attribute in the Facebook response and mail is the name of the attribute in the local user data store. For performance reasons an index on the attribute used should exist on the User Data Store. An alternative configuration could be something like: id=employeenumber In this case id is the facebook id and employeenumber is the attribute in the OpenAM containg the facebook-id. Copyright 2011 ForgeRock AS. All rights reserved Page 6 15/06/10

7 Attribute Mapper Configuration For this use case, this configuration is not relevant last_name=sn first_name=givenname name=cn Again, the left side are the names of the attributes in the facebook response and the right names are the names in the local user data store. Save Attributes in Session Not necessarily enabled. You can disable it if you don't need the attributes (sn, mail, givenname and cn from the Attribute Mapper) to be stored in the session. Create account if it does not exist If you don't want to allow the creation of accounts on the fly disable this option. In this case if the user does not exist, a message stating that the user does not ahev a profile in the organization will appear. Prompt for password setting and activation code Disabled if we are not creating accounts on the fly Map to anonymous user Disabled OAuth 2.0 Provider logout service If we want to allow to logout from the Oauth 2.0 service when logging out from OpenAM, configure the facebook logout service: Logout options Specify if the user will be propmted, automatically logged out or not from the OAuth 2.0 service The SMTP Options are relevant only when we are creating accounts on the fly and we want to send an activation code. Use case 2: Authenticate the users from facebook in OpenAM even if there is no user profile in the local Data Store Users are authenticated in facebook and we want them to get authenticated in OpenAM Copyright 2011 ForgeRock AS. All rights reserved Page 7 15/06/10

8 even if there is no account in the user data store. In this case we are interested in saving some of the attributes coming from facebook as OpenAM Session attributes. The OpenAM principal name will be the content of the attribute configured in the Account Mapper, for example the address or the id from facebook For this use case it is necessary to change the Ignore Profile option in the Authentication Core Settings of the realm. Proxy URL Specify the URL of the OpenAM OAuth 2.0 Proxy. In the example it will be: Account Mapper Configuration: This is the attribute (or attributes) that will be used to search the users in the local user store. is the name of the attribute in the Facebook response and mail is the name of the attribute in the local user data store. For performance reasons an index on the attribute used should exist on the User Data Store. An alternative configuration could be something like: id=employeenumber In this case id is the facebook id and employeenumber is the attribute in the OpenAM containg the facebook-id. For this use case the Authenticted principal will be the content of the OpenAM attribute configured on the right side (mail or employeenumber) Attribute Mapper Configuration For this use case, if you want to save some attributes in the session, configure it aprropriately. last_name=sn first_name=givenname name=cn id=facebook-id Again, the left side are the names of the attributes in the facebook response and the right names are the names in the local user data store or the name of the attributes that will be saved in the session. Copyright 2011 ForgeRock AS. All rights reserved Page 8 15/06/10

9 Save Attributes in Session This could be enabled for this use case so the attributes of the attribute mapper are stored in the session. Create account if it does not exist If you don't want to allow the creation of accounts on the fly disable this option. In this case if the user does not exist, a message stating that the user does not have a profile in the organization will appear. For this use case we want to authenticate users even if there is no profile in the user data store, so it is necessary to change the Profile option to Ignore in the Authentication Core Settings of the realm. Prompt for password setting and activation code Disabled if we are not creating accounts on the fly Map to anonymous user Disabled OAuth 2.0 Provider logout service If we want to allow to logout from the Oauth 2.0 service when logging out from OpenAM, Copyright 2011 ForgeRock AS. All rights reserved Page 9 15/06/10

10 configure the facebook logout service: Logout options Specify if the user will be prompted, automatically logged out or not from the OAuth 2.0 service The SMTP Options are relevant only when we are creating accounts on the fly and we want to send an activation code. Use case 3: Authenticate the users from facebook in OpenAM and create users on the fly if they do not exist, without prompting anything else. For this use case, the OpenAM will look for an account that can be mapped according to the Account Mapper, if the account is not found one will be created on the fly for the user, but the suer will need to set a password first and an activation code will be sent prior to the creation of the profile. Proxy URL Specify the URL of the OpenAM OAuth 2.0 Proxy. In the example it will be: Account Mapper Configuration: This is the attribute (or attributes) that will be used to search the users in the local user store. is the name of the attribute in the Facebook response and mail is the name of the attribute in the local user data store. For performance reasons an index on the attribute used should exist on the User Data Store. An alternative configuration could be something like: id=employeenumber In this case id is the facebook id and employeenumber is the attribute in the OpenAM containg the facebook-id. For this use case the Authenticted principal will be the content of the OpenAM attribute configured on the right side (mail or employeenumber) Attribute Mapper Configuration For this use case, these are the attributes that will be part of the user profile created on the fly, so be sure that the right side corresponds to valid attributes in your local data store. Example: Copyright 2011 ForgeRock AS. All rights reserved Page 10 15/06/10

11 last_name=sn first_name=givenname name=cn id=employeenumber Again, the left side are the names of the attributes in the facebook response and the right names are the names in the local user data store or the name of the attributes that will be saved in the session. Save Attributes in Session This might not be necessary since the attributes will be stored in the local data store, but it is optional to enable it. Create account if it does not exist This option must be enabled for this use case. In this case if the user does not exist, the account will be created on the fly. The account will have a uid that is dynamically created as a UUID and the attributes of the profile will be the ones configured in the attribute mapper configuration. Prompt for password setting and activation code Enable it, since we want to ask the users to set their password and we want them to verify that they are real users by sending an activation code that will be sent to them to their account configured in their facebook profile Map to anonymous user Disabled OAuth 2.0 Provider logout service If we want to allow to logout from the Oauth 2.0 service when logging out from OpenAM, configure the facebook logout service: Logout options Specify if the user will be prompted, automatically logged out or not from the OAuth 2.0 service SMTP Options The SMTP Options are relevant only when we are creating accounts on the fly and we want to send an activation code. Copyright 2011 ForgeRock AS. All rights reserved Page 11 15/06/10

12 Use case 4: Authenticate the users from facebook in OpenAM and create users on the fly, but this time prompt the users to set a password and create the account only if they provide an activation code. For this use case, the OpenAM will look for an account that can be mapped according to the Account Mapper, if the account is not found one will be created on the fly for the user. Proxy URL Specify the URL of the OpenAM OAuth 2.0 Proxy. In the example it will be: Account Mapper Configuration: This is the attribute (or attributes) that will be used to search the users in the local user store. is the name of the attribute in the Facebook response and mail is the name of the attribute in the local user data store. For performance reasons an index on the attribute used should exist on the User Data Store. An alternative configuration could be something like: id=employeenumber In this case id is the facebook id and employeenumber is the attribute in the OpenAM containg the facebook-id. Attribute Mapper Configuration For this use case, these are the attributes that will be part of the user profile created on the fly, so be sure that the right side corresponds to valid attributes in your local data store. Example: last_name=sn first_name=givenname name=cn id=employeenumber Again, the left side are the names of the attributes in the facebook response and the right names are the names in the local user data store or the name of the attributes that will be saved in the session. Copyright 2011 ForgeRock AS. All rights reserved Page 12 15/06/10

13 Save Attributes in Session This might not be necessary since the attributes will be stored in the local data store, but it is optional to enable it. attribute in OAuth2 Response Specify here the name of the attribute in the OAuth 2.0 that contains the address of the user authenticated. In the case of facebook, the attribute is Create account if it does not exist This option must be enabled for this use case. In this case if the user does not exist, the account will be created on the fly. The account will have a uid that is dynamically created as a UUID and the attributes of the profile will be the ones configured in the attribute mapper configuration. Before creating the account the user will be prompted to set the password for the account and to provide an activation code Prompt for password setting and activation code Enable this option. The system will prompt the user to set a password before creating the account. In addition, the user will be sent an activation code to the address configured in their OAuth2.0 account (Configuration parameter attribute in OAuth2 Response ). Customization of the Password Setting page The OAuth2Pwd.jsp located under /<deployed_openam_directory>/config/auth/default/ can be customized to the desired look and feel, just keep the form and the field names as they are. If you are using a different locale, use the file under /openam/config/auth/default_xx/ wher XX corresponds to your locale code. An alternative to customize locale is using the file <deployed_openam_directory>/web- INF/classes/amAuthOAuth.properties (or the one used in your locale). Under the section Password setting page. Also notice that the password setting rules are validated by a javascript, you can change these rules, but keep in mind that at the end, it all depends on the password rules enabled in the user data store (LDAP Server, for example). The OpenAM will not validate these rules. Customization of the Activation Code page The text of the can be customized with the property activationcodemsg from the file <deployed_openam_directory>/web-inf/classes/amauthoauth.properties (or the one used in your locale). For the Activation code page presented to the user, the OpenAM will use the JSP OauthActivate.jsp located under /<deployed_openam_directory>/config/auth/default/. If you are using a different locale, use the file under /openam/config/auth/default_xx/ where XX corresponds to your locale code. You can customize this page to your look and feel. Copyright 2011 ForgeRock AS. All rights reserved Page 13 15/06/10

14 Map to anonymous user Disabled OAuth 2.0 Provider logout service If we want to allow to logout from the Oauth 2.0 service when logging out from OpenAM, configure the facebook logout service: Logout options Specify if the user will be prompted, automatically logged out or not from the OAuth 2.0 service SMTP Gateway implementation class Leave this to use the default implementation, unless you want to create your own. SMTP host Specify the host name of your SMTP gateway SMTP port Specify the port used by the SMTP service in your SMTP Host SMTP User Name If your SMTP host requires a user name, specify it here. SMTP User Password If your SMTP host requires a user name, specify its password here. SMPT SSL Enabled If your SMTP Server uses SSL, enable this option Note, if you use an external SMTP host, then you must provide a port, user and password, otherwise the SMTP server will default to localhost. Use case 5: Authenticate the users from facebook in OpenAM and map to an anonymous account if accounts can not be mapped to a local user. For this use case, the OpenAM will try to map the users to the accounts based on the account mapper, if the account does not exist locally, the user authenticated in facebook will be mapped to an anonymous user. The OpenAM session can save the attributes obtained from the response from facebook. Copyright 2011 ForgeRock AS. All rights reserved Page 14 15/06/10

15 Proxy URL Specify the URL of the OpenAM OAuth 2.0 Proxy. In the example it will be: Account Mapper Configuration: This is the attribute (or attributes) that will be used to search the users in the local user store. is the name of the attribute in the Facebook response and mail is the name of the attribute in the local user data store. For performance reasons an index on the attribute used should exist on the User Data Store. An alternative configuration could be something like: id=employeenumber In this case id is the facebook id and employeenumber is the attribute in the OpenAM containg the facebook-id. Attribute Mapper Configuration For this use case, these are the attributes that can be saved in the OpenAM session onced they have been mapped from the OAuth 2.0 Profile respomnse. Example: last_name=sn first_name=givenname name=cn id=employeenumber Again, the left side are the names of the attributes in the facebook response and the right names are the names in the local user data store or the name of the attributes that will be saved in the session. Save Attributes in Session Enable this option to save the attributes configured in the Attribute Mapper as part of the OpenAM session attribute in OAuth2 Response Specify here the name of the attribute in the OAuth 2.0 that contains the address of the user authenticated. In the case of facebook, the attribute is . This is not relevant since we will not be creating users on the fly. Copyright 2011 ForgeRock AS. All rights reserved Page 15 15/06/10

16 Create account if it does not exist This option must be disabled if we want to map users not encountered to the anonymous user. Prompt for password setting and activation code Disable this option for this use case Map to anonymous user Enabled. Anonymous User The name of the user that will act as anonymous. The user must exist in the realm where the authentication module is configured. The default is anonymous and this user exist only in the top realm by default. OAuth 2.0 Provider logout service If we want to allow to logout from the OAuth 2.0 service when logging out from OpenAM, configure the facebook logout service: Logout options Specify if the user will be prompted, automatically logged out or not from the OAuth 2.0 service SMTP Options The SMTP Options are relevant only when we are creating accounts on the fly and we want to send an activation code. Copyright 2011 ForgeRock AS. All rights reserved Page 16 15/06/10