Social Login (OAuth)
The portal supports logging in users against several Oauth providers:
- SAML
When a user logs in with one of these platforms, a local account will be created and the user will be logged in with that account. At that point, the user can proceed to purchase a usage plan from the plans associated with the strategy and the current captive/landing portal. If there is only one plan and it is free, it will be applied for the user automatically. If there are no usage plans associated with the strategy, the usage plans are controlled by the normal captive/landing portal logic. The user may continue to log in via the social provider on return visits, and they will be logged into their existing account.
The information returned from the provider's API will also be stored into a Social Profile record associated with the account, which may be viewed by clicking on the 'Social Logins' submenu item on the 'Archives::Portal Logs' page.
Requirements
Utilizing an Oauth login flow requires first creating an application with the desired provider, and Oauth login must be enabled in the application. The steps required to do this vary by provider, and are subject to change in the future, but a general outline is below.
A WAN Target should be associated with the Captive Portal where you intend to use the strategy which allows the user to access the provider's site for the login process. Twitter, Facebook, and Google WAN Targets are created automatically and should be selected when utilizing these providers.
If you have not done so, you will need to upgrade your personal Facebook account to a developer account.You may do this, as well as register the app for your business at the following link:
- https://developers.facebook.com/docs/apps/register When prompted for choose a platform, select "Website (WWW)".You will need to specify a category for your application before you make make the app live.
Once you have created the app, go to your Facebook developers dashboard, and add the 'Facebook Login' product to your app. In the 'Client OAuth Settings' dialog, ensure that the 'Web OAuth Login' option is set to YES.
After making any other desired changes to the application (image, etc), copy your App ID and App Secret from the Basic Settings page, as they will be used in the configuration on the rXg.
IMPORTANT: In order for Facebook to allow OAuth requests from this rXg, the redirect URIs must be whitelisted in your app's Facebook Login settings. Complete the section below titled Configuration , then click the show link in the Social Login Strategies scaffold next to Facebook strategy you created. Obtain the list of OAuth Redirect URIs which must be entered within the Facebook developer console's Facebook Login settings section. If this step is not completed, users will experience an error when Facebook login is initiated.
Based on the current configuration of this rXg, the following URIs may need to be added to the application:
Before your app can be used by the public, you must make it 'live' by going to the App Review page and taking the app out of development by setting the toggle to 'YES'. By default, the rXg does not ask for any user permissions that require Facebook to review the application before going live.
Visit the Twitter Apps page to create your app:
- https://apps.twitter.com/ Click 'Create New App' and fill out the resulting form.
Give the app a name and description. The website and Callback URL fields must also be filled out. The website can be your business' main website, or the address of the rXg. The Callback URL will be provided by the rXg during authentication, but we must enter any URL here in order for OAuth to be enabled for the app.
Once you've created your application and customized it as desired, go to the 'Keys and Access Tokens' to obtain your API Key and API Secret which will be utilized in the configuration of the rXg.
IMPORTANT: In order for Twitter to allow OAuth requests from this rXg, the redirect URIs must be whitelisted in your app's redirect URI list. Complete the section below titled Configuration , then click the show link in the Social Login Strategies scaffold next to the Twitter strategy you created. Obtain the list of OAuth Redirect URIs which must be entered into the application's Callback URLs field of the application's settings tab. If this step is not completed, users will experience an error when Twitter login is initiated.
Based on the current configuration of this Rxg, the following URIs may need to be added to the application:
- Go to https://console.developers.google.com
- under the 'Select a project' dropdown, select or create a new app.
- Click 'Library' on the left.
- Enable the "Contacts API" and "Google+ API" (optional -- this is not required to provide credential verification functionality).
- Go to 'Credentials' on the left, then select the 'OAuth consent screen' tab on top, and provide an 'EMAIL ADDRESS' and a 'PRODUCT NAME'
- Wait 10 minutes for changes to take effect.
- Click 'Create Credentials' and choose 'OAuth Client ID'
- Choose 'Web Application' and give it a name
- IMPORTANT: Google requires that the complete Redirect URI be entered, rather than just the hostname. Based on the current configuration of this rXg, the following URIs should be added to the application:
- Enter the client ID and client Secret into the social login configuration
Visit the Instagram Developer page to create your app:
- http://instagram.com/developer/ Click 'Register Your Application' and fill out the resulting form to register as a developer if you are not already. Register a new Client ID and fill out name, description, and other mandatory fields.
Once you've created your application and customized it as desired, click 'Manage' to obtain your Client ID and Client Secret which will be utilized in the configuration of the rXg.
IMPORTANT: In order for Instagram to allow OAuth requests from this rXg, the redirect URIs must be whitelisted in your app's redirect URI list. Complete the section below titled Configuration , then click the show link in the Social Login Strategies scaffold next to the Instagram strategy you created. Obtain the list of OAuth Redirect URIs which must be entered into the application's Valid redirect URIs field of the application's security settings. To access these settings, click the Manage Clients button at the top of the Instagram Developers console, and click the Manage button next to the client you registered in the previous step, then click the Security tab. If this step is not completed, users will experience an error when Instagram login is initiated.
Based on the current configuration of this rXg, the following URIs may need to be added to the application:
Visit the LinkedIn Apps page to create your app:
- https://www.linkedin.com/secure/developer Click 'Create Application' button and fill out the resulting form.
Once you've created your application, go to the Authentication portion of the Application's settings to obtain your Client ID and Client Secret which will be utilized in the configuration of the rXg. You may also choose to include the r_emailaddress default application permission to allow for retrieval of the user's Email address after authentication.
IMPORTANT: In order for LinkedIn to allow OAuth requests from this rXg, the redirect URIs must be whitelisted in your app's redirect URI list. Complete the section below titled Configuration , then click the show link in the Social Login Strategies scaffold next to Facebook strategy you created. Obtain the list of OAuth Redirect URIs which must be added to the application's OAuth 2.0 Authorized Redirect URLs within the settings section. If this step is not completed, users will experience an error when LinkedIn login is initiated.
Based on the current configuration of this Rxg, the following URIs may need to be added to the application:
SAML
Configuration begins by creating a Social Login Strategy on the rXg. This can be accomplished on the System::Portals view.
Next, enter the Identity Provider's metadata URL into the IdP Metadata URL field. The rXg will retrieve the metadata from the Identity Provider and attempt to locate the Single Sign-On URL and Fingerprint. If the remote metadata cannot be retrieved or parsed, the values may be entered manually.
After the record has been saved, click the show link. Depending on the configured usage plans, captive portals, and cluster nodes, one or more metadata URLs will be listed. These can be provided to the Identity Provider out of band to be established as a Service Provider for login trust.
Visit the following URL for an introduction to the concepts of SAML oauth login:
Omniauth Strategies
The Social Login Strategies scaffold enables creation, modification, and deletion of login strategies for supported Omniauth providers.
The name field identifies this login strategy in the system.
The provider name field determines which Oauth provider this strategy relates to. Select a supported provider from the list.
The app ID field defines the ID of the application that has been created with the provider chosen in the provider name field. For Facebook, this is the App ID , but for Twitter this is the API Key. This value should be obtained from the developer console of the associated provider.
The app secret field defines the app's secret value which authenticates the app. This value should be obtained from the developer console of the associated provider.
The captive portals selections define for which captive portals this strategy is enabled. This strategy will not be available unless it is associated with at least one captive portal.
The usage plans selections determine which usage plans are available for users who log in using this strategy. The plans selected here must also be associated with the end user's effective portal; however, users who have not logged in via this strategy won't be able to see these plans in the usage plan list. If there are no usage plans associated with this strategy, an account will be created for the user, who will then be redirected to the usage plan list view. If there is only one associated usage plan, and it is free, the plan will automatically be applied to the account.
The SAML section contains configuration options which pertain only to SAML login strategies. When utilizing a SAML strategy, the App ID and App Key are not necessary.
A SAML configuration requires at a minimum, an Identity Provider (IdP) SSO URL, and optionally, a IdP Cert Fingerprint to enable validation of the IdP's certificate. Both the SSO URL and Fingerprint may be determined automatically by providing a IdP metadata URL.
The Service Provider (SP) Entity ID is a unique identifier for the service provider, which will be entered into the IdP when adding the SP.
After creating the login strategy , the webserver will restart. Clicking the show link will provide the metadata URL that can be provided out-of-band to the Identity Provider in order to establish a login trust.
Users who log in with an Omniauth strategy only have access to usage plans that are associated with their strategy AND the current captive portal. Users who log in with a non-social account do not have access to the usage plans associated with the portal's Omniauth strategies.
The note field is a place for the administrator to enter a comment. This field is purely informational and has no bearing on the configuration settings.
A WAN target should be associated with the captive portal where the operator intends to use the strategy which allows the user to access the provider's site for the login process. Twitter, Facebook, and Google WAN targets are created automatically and should be selected when utilizing these providers.
Customized Login Flow
If you wish to customize the actions taken when a user successfully logs in with a defined strategy, you may override the <provider>_success and <provider>_failure actions of the portal controller (ie, facebook_success or twitter_failure).
