DO313 - ch04s03

Bookmark this page

Integrating Social Login with Red Hat Single Sign-On

Objectives

Integrate third-party identity providers to secure RH-SSO applications.

Identity Brokering

An identity broker is a service that connects clients with identity providers (IdPs). The identity broker uses the identities from the external IdP to access the services from the service provider. The identity broker delegates the authentication and authorization to the external IdP.

You can use identity brokering to provide a better experience to the users, because they can use an existing account in an external IdP to authenticate and sign up in your client. Thus, the users do not need to create separate accounts for every client, and the clients do not need to know the user credentials. Examples of IdPs are social providers such as Facebook or Google, a business partner whose users need to access your services, or a cloud-based identity service that you want to integrate in your infrastructure.

RH-SSO can integrate third-party IdPs by using a set of open standard protocols such as SAML, OpenID Connect (OIDC), or OAuth2. RH-SSO acts as an intermediary service for authenticating and replicating users from the targeted IdP. After RH-SSO creates the users, and imports their information from the IdP, they become users of your realm. Then, they can use all of the RH-SSO features and they must respect the realm's security constraints. In RH-SSO, you can link a user account with one or more identities from IdPs.

RH-SSO Identity Brokering Overview

When using RH-SSO as an identity broker, users can authenticate in a specific realm by using their credentials or select one of the configured IdPs. You can also configure a default IdP in RH-SSO to directly redirect users to that IdP.

When there is an identity broker in an RH-SSO realm, then RH-SSO applies the First Broker Login authentication flow. The following is the definition of the First Broker Identity authentication flow:

	The unauthenticated user requests a resource from the service provider.
	The client application redirects the user to the identity broker for authentication. RH-SSO acts as the identity broker.
	RH-SSO displays the login page with a list of the configured IdPs for the realm.
	The user selects one of the IdPs.
	RH-SSO sends an authentication request to the target IdP requesting authentication. Then, redirects the user to the identity provider's login page.
	The user provides credentials to authenticate with the IdP.
	After the user successfully authenticates with the IdP, RH-SSO gets an authentication response. The response contains a security token used by RH-SSO to trust the identity provider's authentication and retrieve user information.
	RH-SSO checks if the response from the IdP is valid. Then, RH-SSO checks whether the user exists in its local database. If the user does not exist in its local database, then RH-SSO imports and creates the user. If the token does not contain the user information, then RH-SSO asks the IdP for further user information, which is called identity federation. If the user exists in its local database, then RH-SSO might ask the user to link the user identity returned from the IdP with the existing account. This process is called account linking. After this process, RH-SSO authenticates the user and issues its token to access the requested resource in the service provider.
	RH-SSO redirects the user to the service provider by sending the token previously issued during the local authentication.
	The service provider receives the token from RH-SSO and permits access to the protected resource.

Figure 4.6: Example of social login

There are two types of IdPs:

Social providers: These providers enable social authentication in your realm. With RH-SSO, users can log in to your client by using a social network account.
Standard-based providers: These providers rely on specific standards to authenticate and authorize users. By using these providers, you can connect to any IdP compliant with a specific standard. As stated elsewhere in this course, RH-SSO provides support for SAML and OIDC standards. You can configure and broker any IdP based on these open standards.

Create and Configure an Identity Provider

You can create and configure an IdP by using the RH-SSO Admin Console. Navigate to the RH-SSO Admin Console URL and click Configure → Identity Providers.

Figure 4.7: Identity provider creation screen

In the Add provider drop-down menu you can select between a custom IdP using SAML or OIDC standards, or a social IdP. RH-SSO supports the following social IdPs: GitHub, Facebook, Google, LinkedIn, Instagram, Microsoft, BitBucket, Twitter, OpenShift, GitLab, PayPal, and Stack Overflow.

After you select the social IdP, RH-SSO shows the configuration page.

Figure 4.8: Identity provider configuration screen

The following table summarizes some of the most important configuration options that are common to all the IdPs:

Table 4.1. Common IdPs configuration options

Parameter	Description
Alias	The alias is the identifier for the IdP. RH-SSO uses the alias to build the redirect uniform resource identifier (URI).
Store Tokens	If you enable this switch, then RH-SSO stores the tokens after user authentication.
Stored Tokens Readable	If you enable this switch, then users can retrieve the stored IdP token.
Enabled	Use this switch to enable and disable the IdP.
Trust Email	Use this switch to trust the user email information from the IdP. This action automatically skips the user email validation even if the realm configuration requires it.
Account Linking Only	If you enabled this switch, then RH-SSO only uses this provider to link existing accounts. This provider cannot log in users and RH-SSO does not display it in the login page.
Hide on Login Page	Use this switch to hide or show the IdP from the login page. If you hide the IdP, then users and clients can still log in through this provider if they request it explicitly, for example by using the `kc_idp_hint` parameter.
GUI Order	Number defining the order of the provider in the login page.
First Login Flow	The alias for the RH-SSO authentication flow after the first user login.
Post Login Flow	The alias for the RH-SSO authentication flow after each user login.
Sync Mode	Synchronization mode for all the user mappers. You can select between three options: `legacy` to use the current RH-SSO behavior regarding mappers, `import` to import the user data only during the first login, and `force` to update the user data every time the user logs in.

You can hover over the question mark symbol (?) next to each configuration option to show more information. Note that for each social IdP, the configuration page requires different configuration parameters.

Note

You can find more information for each different social IdP in the Integrating identity providers section in the Server Administrator Guide documentation at https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.6/html-single/server_administration_guide/index#identity_broker

For example, if you configure OpenShift v4 as your social IdP, then you need to provide the Red Hat OpenShift client ID, client secret, and the base URL for the Red Hat OpenShift API.

Red Hat OpenShift acts as an identity provider. Thus, in a similar way to RH-SSO, you must create the OAuth2 client, the RH-SSO servers, for the identity provider, and the Red Hat OpenShift OAuth2 cluster. The procedure to configure Red Hat OpenShift as the social IdP is as follows:

Start creating the OpenShift v4 user IdP in RH-SSO. To do so, navigate to the RH-SSO web UI URL and click Configure → Identity Providers. In the Add provider drop-down menu select Openshift v4.
The social IdP configuration screen appears. Take note of the automatically generated redirect URI.
Log in to your Red Hat OpenShift cluster and create an OAuthClient custom resource. You can use the following YAML file as an example. Note that the redirectURI line has been split so that it displays correctly in the PDF guide. Do not add the line break in your YAML file.
```
kind: OAuthClient
apiVersion: oauth.openshift.io/v1
metadata:
  name: mycustomresource
secret: mysecret
redirectURIs:
  - "https://sso.lab.example.com:8080/auth/realms/myrealm/broker/openshift-v4/endpoint"
grantMethod: prompt
```
Note that the redirect URI parameter is the one you copy from the RH-SSO social IdP configuration page. Then, create the Red Hat OpenShift OAuthClient custom resource by using the oc create command.
Change to the RH-SSO social IdP configuration page. Fill the Red Hat OpenShift client ID, client secret, and the base URL for the Red Hat OpenShift API with the values from your Red Hat OpenShift OAuthClient custom resource. Click Save.

After this procedure, your OpenShift social IdP is configured in RH-SSO.

First Broker Login Authentication Flow

When you add an IdP to RH-SSO, it selects by default the First Broker Login authentication flow to be used after the first user login. You can create new authentication flows and select them to perform different actions after the first user login.

Figure 4.9: First broker login authentication flow

The default First Broker Login authentication flow follows the next authentication steps:

Review Profile (review profile config): This authenticator might display the profile info page, where users can review their profile retrieved from an IdP. You can configure the authenticator in the Actions → Config menu, where you can set three different values for the Update Profile On First Login option:
- on: RH-SSO always show the profile page to the user asking for additional information.
- missing: RH-SSO only presents the profile page to the users if the IdP does not provide mandatory information such as the email, first name, or last name.
- off: RH-SSO does not show the profile page to the user.
User Creation Or Linking: This flow is for the existing and non-existing user alternatives. It is the parent flow for the following sub-flows.
Create User If Unique (create unique user config): This sub-flow checks if there is an existing RH-SSO account with the same email or username. If the account does not exist, then RH-SSO creates a new user account and links it with the identity from the IdP. Then, as this option is marked as alternative, the flow finishes. If the account exists, then it continues to the Handle Existing Account sub-flow.
Handle Existing Account: This sub-flow handles what to do if there is an existing RH-SSO account with the same email or username. It is the parent flow for the following sub-flows.
Confirm Link Existing Account: RH-SSO shows to the user that there is an existing account with the same email or username. Then, the user can link the IdP account with the RH-SSO account, or modify the email or username. The latter option restarts the complete flow.
Account Verification Options: This sub-flow handles which method RH-SSO uses to verify the user account. It is the parent flow for the following sub-flows.
Verify Existing Account By Email: This authenticator sends an email to the users so they can verify that they want to link the IdP with the RH-SSO account. This option only works if you configure the SMTP server for the realm. If the user verifies the account by using email, then the flow finishes, because this sub-flow is marked as alternative.
Verify Existing Account By Reauthentication: If the email authenticator is disabled or the SMTP server is not configured for the realm, then RH-SSO uses this authenticator. It displays to the user a login screen to authenticate with the password to link the IdP account with the RH-SSO account. It is the parent flow for the following sub-flows.
Username Password Form For Identity Provider Reauthentication: This authenticator validates a password from the login form.
First Broker Login - Conditional OTP: This sub-flow determines whether RH-SSO requires a one-time password (OTP) for authentication. It is a conditional flow and it executes depending on the result of the following Condition - User Configured execution. If the result is true, then RH-SSO loads the executions for this sub-flow and processes them.
Condition - User Configured: This authentication checks whether RH-SSO has configured other executions in the flow for the user. The First Broker Login - Conditional OTP sub-flow executes only when the user has a configured OTP credential.
OTP Form: This execution shows the OTP form to the user. This execution only runs when the user has an OTP credential set up.

References

For more information about integrating identity providers in RH-SSO, refer to the Integrating identity providers section in the Server Administration Guide documentation at https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.6/html-single/server_administration_guide/index#identity_broker

For more information about authentication flows, refer to the Authentication flows section in the Server Administration Guide documentation at https://access.redhat.com/documentation/en-us/red_hat_single_sign-on/7.6/html-single/server_administration_guide/index#authentication-flows

Revision: do313-7.6-bc10333

Red Hat Single Sign-On Administration