Chapter 12. Identity Brokering An Identity Broker is an intermediary service that connects multiple service providers with different identity providers. As an intermediary service, the identity broker is responsible for creating a trust relationship with an external identity provider in order to use its identities to access internal services exposed by service providers. From a user perspective, an identity broker provides a user-centric and centralized way to manage identities across different security domains or realms. An existing account can be linked with one or more identities from different identity providers or even created based on the identity information obtained from them. An identity provider is usually based on a specific protocol that is used to authenticate and communicate authentication and authorization information to their users. It can be a social provider such as Facebook, Google or Twitter. It can be a business partner whose users need to access your services. Or it can be a cloud-based identity service that you want to integrate with. Usually, identity providers are based on the following protocols: SAML v2.0 OpenID Connect v1.0 OAuth v2.0 In the sections we'll see how to configure and use Red Hat Single Sign-On as an identity broker, covering some important aspects such as: Social Authentication OpenID Connect v1.0 Brokering SAML v2.0 Brokering Identity Federation 12.1. Brokering Overview When using Red Hat Single Sign-On as an identity broker, users are not forced to provide their credentials in order to authenticate in a specific realm. Instead, they are presented with a list of identity providers from which they can authenticate. You can also configure a default identity provider. In this case the user will not be given a choice, but will instead be redirected directly to the default provider. The following diagram demonstrates the steps involved when using Red Hat Single Sign-On to broker an external identity provider: Identity Broker Flow User is not authenticated and requests a protected resource in a client application. The client applications redirects the user to Red Hat Single Sign-On to authenticate. At this point the user is presented with the login page where there is a list of identity providers configured in a realm. User selects one of the identity providers by clicking on its respective button or link. Red Hat Single Sign-On issues an authentication request to the target identity provider asking for authentication and the user is redirected to the login page of the identity provider. The connection properties and other configuration options for the identity provider were previously set by the administrator in the Admin Console. User provides his credentials or consent in order to authenticate with the identity provider. Upon a successful authentication by the identity provider, the user is redirected back to Red Hat Single Sign-On with an authentication response. Usually this response contains a security token that will be used by Red Hat Single Sign-On to trust the authentication performed by the identity provider and retrieve information about the user. Now Red Hat Single Sign-On is going to check if the response from the identity provider is valid. If valid, it will import and create a new user or just skip that if the user already exists. If it is a new user, Red Hat Single Sign-On may ask the identity provider for information about the user if that info doesn't already exist in the token. This is what we call identity federation . If the user already exists Red Hat Single Sign-On may ask him to link the identity returned from the identity provider with the existing account. We call this process account linking . What exactly is done is configurable and can be specified by setup of First Login Flow . At the end of this step, Red Hat Single Sign-On authenticates the user and issues its own token in order to access the requested resource in the service provider. Once the user is locally authenticated, Red Hat Single Sign-On redirects the user to the service provider by sending the token previously issued during the local authentication. The service provider receives the token from Red Hat Single Sign-On and allows access to the protected resource. There are some variations of this flow that we will talk about later. For instance, instead of presenting a list of identity providers, the client application can request a specific one. Or you can tell Red Hat Single Sign-On to force the user to provide additional information before federating his identity. Note Different protocols may require different authentication flows. At this moment, all the identity providers supported by Red Hat Single Sign-On use a flow just like described above. However, regardless of the protocol in use, user experience should be pretty much the same. As you may notice, at the end of the authentication process Red Hat Single Sign-On will always issue its own token to client applications. What this means is that client applications are completely decoupled from external identity providers. They don't need to know which protocol (eg.: SAML, OpenID Connect, OAuth, etc) was used or how the user's identity was validated. They only need to know about Red Hat Single Sign-On. 12.2. Default Identity Provider It is possible to automatically redirect to a identity provider instead of displaying the login form. To enable this go to the Authentication page in the administration console and select the Browser flow. Then click on config for the Identity Provider Redirector authenticator. Set Default Identity Provider to the alias of the identity provider you want to automatically redirect users to. If the configured default identity provider is not found the login form will be displayed instead. This authenticator is also responsible for dealing with the kc_idp_hint query parameter. See client suggested identity provider section for more details. 12.3. General Configuration The identity broker configuration is all based on identity providers. Identity providers are created for each realm and by default they are enabled for every single application. That means that users from a realm can use any of the registered identity providers when signing in to an application. In order to create an identity provider click the Identity Providers left menu item. Identity Providers In the drop down list box, choose the identity provider you want to add. This will bring you to the configuration page for that identity provider type. Add Identity Provider Above is an example of configuring a Google social login provider. Once you configure an IDP, it will appear on the Red Hat Single Sign-On login page as an option. IDP login page Social Social providers allow you to enable social authentication in your realm. Red Hat Single Sign-On makes it easy to let users log in to your application using an existing account with a social network. Currently supported providers include: Twitter, Facebook, Google, LinkedIn, Instagram, Microsoft, PayPal, Openshift v3, GitHub, GitLab, Bitbucket, and Stack Overflow. Protocol-based Protocol-based providers are those that rely on a specific protocol in order to authenticate and authorize users. They allow you to connect to any identity provider compliant with a specific protocol. Red Hat Single Sign-On provides support for SAML v2.0 and OpenID Connect v1.0 protocols. It makes it easy to configure and broker any identity provider based on these open standards. Although each type of identity provider has its own configuration options, all of them share some very common configuration. Regardless of which identity provider you are creating, you'll see the following configuration options available: Table 12.1. Common Configuration Configuration Description Alias The alias is a unique identifier for an identity provider. It is used to reference an identity provider internally. Some protocols such as OpenID Connect require a redirect URI or callback url in order to communicate with an identity provider. In this case, the alias is used to build the redirect URI. Every single identity provider must have an alias. Examples are facebook , google , idp.acme.com , etc. Enabled Turn the provider on/off. Hide on Login Page When this switch is on, this provider will not be shown as a login option on the login page. Clients can still request to use this provider by using the 'kc_idp_hint' parameter in the URL they use to request a login. Account Linking Only When this switch is on, this provider cannot be used to login users and will not be shown as an option on the login page. Existing accounts can still be linked with this provider though. Store Tokens Whether or not to store the token received from the identity provider. Stored Tokens Readable Whether or not users are allowed to retrieve the stored identity provider token. This also applies to the broker client-level role read token . Trust Email If the identity provider supplies an email address this email address will be trusted. If the realm required email validation, users that log in from this IDP will not have to go through the email verification process. GUI Order The order number that sorts how the available IDPs are listed on the login page. First Login Flow This is the authentication flow that will be triggered for users that log into Red Hat Single Sign-On through this IDP for the first time ever. Post Login Flow Authentication flow that is triggered after the user finishes logging in with the external identity provider. 12.4. Social Identity Providers For Internet facing applications, it is quite burdensome for users to have to register at your site to obtain access. It requires them to remember yet another username and password combination. Social identity providers allow you to delegate authentication to a semi-trusted and respected entity where the user probably already has an account. Red Hat Single Sign-On provides built-in support for the most common social networks out there, such as Google, Facebook, Twitter, GitHub, LinkedIn, Microsoft and Stack Overflow. 12.4.1. Bitbucket There are a number of steps you have to complete to be able to enable login with Bitbucket. First, open the Identity Providers left menu item and select Bitbucket from the Add provider drop down list. This will bring you to the Add identity provider page. Add Identity Provider Before you can click Save , you must obtain a Client ID and Client Secret from Bitbucket. Note You will use the Redirect URI from this page in a later step, which you will provide to Bitbucket when you register Red Hat Single Sign-On as a client there. Add a New App To enable login with Bitbucket you must first register an application project in OAuth on Bitbucket Cloud . Note Bitbucket often changes the look and feel of application registration, so what you see on the Bitbucket site may differ. If in doubt, see the Bitbucket documentation. Click the Add consumer button. Register App Copy the Redirect URI from the Red Hat Single Sign-On Add Identity Provider page and enter it into the Callback URL field on the Bitbucket Add OAuth Consumer page. On the same page, mark the Email and Read boxes under Account to allow your application to read user email. Bitbucket App Page When you are done registering, click Save . This will open the application management page in Bitbucket. Find the client ID and secret from this page so you can enter them into the Red Hat Single Sign-On Add identity provider page. Click Save . 12.4.2. Facebook There are a number of steps you have to complete to be able to enable login with Facebook. First, go to the Identity Providers left menu item and select Facebook from the Add provider drop down list. This will bring you to the Add identity provider page. Add Identity Provider You can't click save yet, as you'll need to obtain a Client ID and Client Secret from Facebook. One piece of data you'll need from this page is the Redirect URI . You'll have to provide that to Facebook when you register Red Hat Single Sign-On as a client there, so copy this URI to your clipboard. To enable login with Facebook you first have to create a project and a client in the Facebook Developer Console . Note Facebook often changes the look and feel of the Facebook Developer Console, so these directions might not always be up to date and the configuration steps might be slightly different. Once you've logged into the console there is a pull down menu in the top right corner of the screen that says My Apps . Select the Add a New App menu item. Add a New App Select the Website icon. Click the Skip and Create App ID button. Create a New App ID The email address and app category are required fields. Once you're done with that, you will be brought to the dashboard for the application. Click the Settings left menu item. Create a New App ID Click on the + Add Platform button at the end of this page and select the Website icon. Copy and paste the Redirect URI from the Red Hat Single Sign-On Add identity provider page into the Site URL of the Facebook Website settings block. Specify Website After this it is necessary to make the Facebook app public. Click App Review left menu item and switch button to "Yes". You will need also to obtain the App ID and App Secret from this page so you can enter them into the Red Hat Single Sign-On Add identity provider page. To obtain this click on the Dashboard left menu item and click on Show under App Secret . Go back to Red Hat Single Sign-On and specify those items and finally save your Facebook Identity Provider. One config option to note on the Add identity provider page for Facebook is the Default Scopes field. This field allows you to manually specify the scopes that users must authorize when authenticating with this provider. For a complete list of scopes, please take a look at https://developers.facebook.com/docs/graph-api . By default, Red Hat Single Sign-On uses the following scopes: email . 12.4.3. GitHub There are a number of steps you have to complete to be able to enable login with GitHub. First, go to the Identity Providers left menu item and select GitHub from the Add provider drop down list. This will bring you to the Add identity provider page. Add Identity Provider You can't click save yet, as you'll need to obtain a Client ID and Client Secret from GitHub. One piece of data you'll need from this page is the Redirect URI . You'll have to provide that to GitHub when you register Red Hat Single Sign-On as a client there, so copy this URI to your clipboard. To enable login with GitHub you first have to register an application project in GitHub Developer applications . Note GitHub often changes the look and feel of application registration, so these directions might not always be up to date and the configuration steps might be slightly different. Add a New App Click the Register a new application button. Register App You'll have to copy the Redirect URI from the Red Hat Single Sign-On Add Identity Provider page and enter it into the Authorization callback URL field on the GitHub Register a new OAuth application page. Once you've completed this page you will be brought to the application's management page. GitHub App Page You will need to obtain the client ID and secret from this page so you can enter them into the Red Hat Single Sign-On Add identity provider page. Go back to Red Hat Single Sign-On and specify those items. 12.4.4. GitLab There are a number of steps you have to complete to be able to enable login with GitLab. First, go to the Identity Providers left menu item and select GitLab from the Add provider drop down list. This will bring you to the Add identity provider page. Add Identity Provider Before you can click Save , you must obtain a Client ID and Client Secret from GitLab. Note You will use the Redirect URI from this page in a later step, which you will provide to GitLab when you register Red Hat Single Sign-On as a client there. To enable login with GitLab you first have to register an application in GitLab as OAuth2 authentication service provider . Note GitLab often changes the look and feel of application registration, so what you see on the GitLab site may differ. If in doubt, see the GitLab documentation. Add a New App Copy the Redirect URI from the Red Hat Single Sign-On Add Identity Provider page and enter it into the Redirect URI field on the GitLab Add new application page. GitLab App Page When you are done registering, click Save application . This will open the application management page in GitLab. Find the client ID and secret from this page so you can enter them into the Red Hat Single Sign-On Add identity provider page. To finish, return to Red Hat Single Sign-On and enter them. Click Save . 12.4.5. Google There are a number of steps you have to complete to be able to enable login with Google. First, go to the Identity Providers left menu item and select Google from the Add provider drop down list. This will bring you to the Add identity provider page. Add Identity Provider You can't click save yet, as you'll need to obtain a Client ID and Client Secret from Google. One piece of data you'll need from this page is the Redirect URI . You'll have to provide that to Google when you register Red Hat Single Sign-On as a client there, so copy this URI to your clipboard. To enable login with Google you first have to create a project and a client in the Google Developer Console . Then you need to copy the client ID and secret into the Red Hat Single Sign-On Admin Console. Note Google often changes the look and feel of the Google Developer Console, so these directions might not always be up to date and the configuration steps might be slightly different. Let's see first how to create a project with Google. Log in to the Google Developer Console . Google Developer Console Click the Create Project button. Use any value for Project name and Project ID you want, then click the Create button. Wait for the project to be created (this may take a while). Once created you will be brought to the project's dashboard. Dashboard Then navigate to the APIs & Services section in the Google Developer Console. On that screen, navigate to Credentials administration. When users log into Google from Red Hat Single Sign-On they will see a consent screen from Google which will ask the user if Red Hat Single Sign-On is allowed to view information about their user profile. Thus Google requires some basic information about the product before creating any secrets for it. For a new project, you have first to configure OAuth consent screen . For the very basic setup, filling in the Application name is sufficient. You can also set additional details like scopes for Google APIs in this page. Fill in OAuth consent screen details The step is to create OAuth client ID and client secret. Back in Credentials administration, navigate to Credentials tab and select OAuth client ID under the Create credentials button. Create credentials You will then be brought to the Create OAuth client ID page. Select Web application as the application type. Specify the name you want for your client. You'll also need to copy and paste the Redirect URI from the Red Hat Single Sign-On Add Identity Provider page into the Authorized redirect URIs field. After you do this, click the Create button. Create OAuth client ID After you click Create you will be brought to the Credentials page. Click on your new OAuth 2.0 Client ID to view the settings of your new Google Client. Google Client Credentials You will need to obtain the client ID and secret from this page so you can enter them into the Red Hat Single Sign-On Add identity provider page. Go back to Red Hat Single Sign-On and specify those items. One config option to note on the Add identity provider page for Google is the Default Scopes field. This field allows you to manually specify the scopes that users must authorize when authenticating with this provider. For a complete list of scopes, please take a look at https://developers.google.com/oauthplayground/ . By default, Red Hat Single Sign-On uses the following scopes: openid profile email . If your organization uses the G Suite and you want to restrict access to only members of your organization, you must enter the domain that is used for the G Suite into the Hosted Domain field to enable it. 12.4.6. LinkedIn There are a number of steps you have to complete to be able to enable login with LinkedIn. First, go to the Identity Providers left menu item and select LinkedIn from the Add provider drop down list. This will bring you to the Add identity provider page. Add Identity Provider You can't click save yet, as you'll need to obtain a Client ID and Client Secret from LinkedIn. One piece of data you'll need from this page is the Redirect URI . You'll have to provide that to LinkedIn when you register Red Hat Single Sign-On as a client there, so copy this URI to your clipboard. To enable login with LinkedIn you first have to create an application in LinkedIn Developer Network . Note LinkedIn may change the look and feel of application registration, so these directions may not always be up to date. Developer Network Click on the Create Application button. This will bring you to the Create a New Application Page. Create App Fill in the form with the appropriate values, then click the Submit button. This will bring you to the new application's settings page. App Settings Select r_basicprofile and r_emailaddress in the Default Application Permissions section. You'll have to copy the Redirect URI from the Red Hat Single Sign-On Add Identity Provider page and enter it into the OAuth 2.0 Authorized Redirect URLs field on the LinkedIn app settings page. Don't forget to click the Update button after you do this! You will then need to obtain the client ID and secret from this page so you can enter them into the Red Hat Single Sign-On Add identity provider page. Go back to Red Hat Single Sign-On and specify those items. 12.4.7. Microsoft There are a number of steps you have to complete to be able to enable login with Microsoft. First, go to the Identity Providers left menu item and select Microsoft from the Add provider drop down list. This will bring you to the Add identity provider page. Add Identity Provider You can't click save yet, as you'll need to obtain a Client ID and Client Secret from Microsoft. One piece of data you'll need from this page is the Redirect URI . You'll have to provide that to Microsoft when you register Red Hat Single Sign-On as a client there, so copy this URI to your clipboard. To enable login with Microsoft account you first have to register an OAuth application at Microsoft. Go to the Microsoft Application Registration url. Note Microsoft often changes the look and feel of application registration, so these directions might not always be up to date and the configuration steps might be slightly different. Register Application Enter in the application name and click Create application . This will bring you to the application settings page of your new application. Settings You'll have to copy the Redirect URI from the Red Hat Single Sign-On Add Identity Provider page and add it to the Redirect URIs field on the Microsoft application page. Be sure to click the Add Url button and Save your changes. Finally, you will need to obtain the Application ID and secret from this page so you can enter them back on the Red Hat Single Sign-On Add identity provider page. Go back to Red Hat Single Sign-On and specify those items. Warning From November 2018 onwards, Microsoft is removing support for the Live SDK API in favor of the new Microsoft Graph API. The Red Hat Single Sign-On Microsoft identity provider has been updated to use the new endpoints so make sure to upgrade to Red Hat Single Sign-On version 7.2.5 or later in order to use this provider. Furthermore, client applications registered with Microsoft under "Live SDK applications" will need to be re-registered in the Microsoft Application Registration portal to obtain an application id that is compatible with the Microsoft Graph API. 12.4.8. OpenShift 3 Note OpenShift Online is currently in the developer preview mode. This documentation has been based on on-premise installations and local minishift development environment. There are a just a few steps you have to complete to be able to enable login with OpenShift. First, go to the Identity Providers left menu item and select OpenShift from the Add provider drop down list. This will bring you to the Add identity provider page. Add Identity Provider Registering OAuth client You can register your client using oc command line tool. USD oc create -f <(echo ' kind: OAuthClient apiVersion: v1 metadata: name: kc-client 1 secret: "..." 2 redirectURIs: - "http://www.example.com/" 3 grantMethod: prompt 4 ') 1 The name of your OAuth client. Passed as client_id request parameter when making requests to <openshift_master> /oauth/authorize and <openshift_master> /oauth/token . 2 secret is used as the client_secret request parameter. 3 The redirect_uri parameter specified in requests to <openshift_master> /oauth/authorize and <openshift_master> /oauth/token must be equal to (or prefixed by) one of the URIs in redirectURIs . 4 The grantMethod is used to determine what action to take when this client requests tokens and has not yet been granted access by the user. Use client ID and secret defined by oc create command to enter them back on the Red Hat Single Sign-On Add identity provider page. Go back to Red Hat Single Sign-On and specify those items. Please refer to official OpenShift documentation for more detailed guides. 12.4.9. OpenShift 4 Note Prior to configuring OpenShift 4 Identity Provider, please locate the correct OpenShift 4 API URL up. In some scenarios, that URL might be hidden from users. The easiest way to obtain it is to invoke the following command (this might require installing jq command separately) curl -s -k -H "Authorization: Bearer USD(oc whoami -t)" https://<openshift-user-facing-api-url>/apis/config.openshift.io/v1/infrastructures/cluster | jq ".status.apiServerURL" . In most cases, the address will be protected by HTTPS. Therefore, it is essential to configure X509_CA_BUNDLE in the container and set it to /var/run/secrets/kubernetes.io/serviceaccount/ca.crt . Otherwise, Red Hat Single Sign-On won't be able to communicate with the API Server. There are a just a few steps you have to complete to be able to enable login with OpenShift 4. First, go to the Identity Providers left menu item and select OpenShift v4 from the Add provider drop down list. This will bring you to the Add identity provider page. Add Identity Provider Registering OAuth client You can register your client using oc command line tool. USD oc create -f <(echo ' kind: OAuthClient apiVersion: v1 metadata: name: keycloak-broker 1 secret: "..." 2 redirectURIs: - "<copy pasted Redirect URI from OpenShift 4 Identity Providers page>" 3 grantMethod: prompt 4 ') 1 The name of your OAuth client. Passed as client_id request parameter when making requests to <openshift_master> /oauth/authorize and <openshift_master> /oauth/token . The name parameter needs to be the same in OAuthClient object as well as in Red Hat Single Sign-On configuration. 2 secret is used as the client_secret request parameter. 3 The redirect_uri parameter specified in requests to <openshift_master> /oauth/authorize and <openshift_master> /oauth/token must be equal to (or prefixed by) one of the URIs in redirectURIs . The easiest way to configure it correctly is to copy-paste it from Red Hat Single Sign-On OpenShift 4 Identity Provider configuration page ( Redirect URI field). 4 The grantMethod is used to determine what action to take when this client requests tokens and has not yet been granted access by the user. Use the client ID and secret defined by oc create command to enter them back on the Red Hat Single Sign-On Add identity provider page. Go back to Red Hat Single Sign-On and specify those items. Tip The OpenShift API server returns The client is not authorized to request a token using this method whenever OAuthClient name , secret or redirectURIs is incorrect. Make sure you copy-pasted them into Red Hat Single Sign-On OpenShift 4 Identity Provider page correctly. Please refer to official OpenShift documentation for more detailed guides. 12.4.10. PayPal There are a number of steps you have to complete to be able to enable login with PayPal. First, go to the Identity Providers left menu item and select PayPal from the Add provider drop down list. This will bring you to the Add identity provider page. Add Identity Provider You can't click save yet, as you'll need to obtain a Client ID and Client Secret from PayPal. One piece of data you'll need from this page is the Redirect URI . You'll have to provide that to PayPal when you register Red Hat Single Sign-On as a client there, so copy this URI to your clipboard. To enable login with PayPal you first have to register an application project in PayPal Developer applications . Add a New App Click the Create App button. Register App You will now be brought to the app settings page. Do the following changes Choose to configure either Sandbox or Live (choose Live if you haven't enabled the Target Sandbox switch on the Add identity provider page) Copy Client ID and Secret so you can paste them into the Red Hat Single Sign-On Add identity provider page. Scroll down to App Settings Copy the Redirect URI from the Red Hat Single Sign-On Add Identity Provider page and enter it into the Return URL field. Check the Log In with PayPal checkbox. Check the Full name checkbox under the personal information section. Check the Email address checkbox under the address information section. Add both a privacy and a user agreement URL pointing to the respective pages on your domain. 12.4.11. Stack Overflow There are a number of steps you have to complete to be able to enable login with Stack Overflow. First, go to the Identity Providers left menu item and select Stack Overflow from the Add provider drop down list. This will bring you to the Add identity provider page. Add Identity Provider To enable login with Stack Overflow you first have to register an OAuth application on StackApps . Go to registering your application on Stack Apps URL and login. Note Stack Overflow often changes the look and feel of application registration, so these directions might not always be up to date and the configuration steps might be slightly different. Register Application Enter in the application name and the OAuth Domain Name of your application and click Register your Application . Type in anything you want for the other items. Settings Finally, you will need to obtain the client ID, secret, and key from this page so you can enter them back on the Red Hat Single Sign-On Add identity provider page. Go back to Red Hat Single Sign-On and specify those items. 12.4.12. Twitter There are a number of steps you have to complete to be able to enable login with Twitter. First, go to the Identity Providers left menu item and select Twitter from the Add provider drop down list. This will bring you to the Add identity provider page. Add Identity Provider You can't click save yet, as you'll need to obtain a Client ID and Client Secret from Twitter. One piece of data you'll need from this page is the Redirect URI . You'll have to provide that to Twitter when you register Red Hat Single Sign-On as a client there, so copy this URI to your clipboard. To enable login with Twtter you first have to create an application in the Twitter Application Management . Register Application Click on the Create New App button. This will bring you to the Create an Application page. Register Application Enter in a Name and Description. The Website can be anything, but cannot have a localhost address. For the Callback URL you must copy the Redirect URI from the Red Hat Single Sign-On Add Identity Provider page. Warning You cannot use localhost in the Callback URL . Instead replace it with 127.0.0.1 if you are trying to test drive Twitter login on your laptop. After clicking save you will be brought to the Details page. App Details go to the Keys and Access Tokens tab. Keys and Access Tokens Finally, you will need to obtain the API Key and secret from this page and copy them back into the Client ID and Client Secret fields on the Red Hat Single Sign-On Add identity provider page. 12.4.13. Instagram There are a number of steps you have to complete to be able to enable login with Instagram. First, go to the Identity Providers left menu item and select Instagram from the Add provider drop down list. This will bring you to the Add identity provider page. Add Identity Provider You can't click save yet, as you'll need to obtain a Client ID and Client Secret from Instagram. One piece of data you'll need from this page is the Redirect URI . You'll have to provide that to Instagram when you register Red Hat Single Sign-On as a client there, so copy this URI to your clipboard. To enable login with Instagram you first have to create a project and a client. Instagram API is managed through the Facebook Developer Console . Note Facebook often changes the look and feel of the Facebook Developer Console, so these directions might not always be up to date and the configuration steps might be slightly different. Once you've logged into the console there is a menu in the top right corner of the screen that says My Apps . Select the Add a New App menu item. Add a New App Select For Everything Else . Create a New App ID Fill all required fields. Once you're done with that, you will be brought to the dashboard for the application. In the menu in the left navigation panel select Basic under Settings . Add Platform Select + Add Platform at the bottom and then click [Website] with the globe icon. Specify URL of your site. Add a Product Select Dashboard from the left menu and click Set Up in the Instagram box. In the left menu then select Basic Display under Instagram and click Create New App . Create a New Instagram App ID Specify Display Name . Setup the App Copy and paste the Redirect URI from the Red Hat Single Sign-On Add identity provider page into the Valid OAuth Redirect URIs of the Instagram Client OAuth Settings settings block. You can use this URL also for Deauthorize Callback URL and Data Deletion Request URL . Red Hat Single Sign-On currently doesn't support either of them, but the Facebook Developer Console requires both of them to be filled. You will need also to obtain the App ID and App Secret from this page so you can enter them into the Red Hat Single Sign-On Add identity provider page. To obtain this click on Show under App Secret . Go back to Red Hat Single Sign-On and specify those items and finally save your Instagram Identity Provider. After this it is necessary to make the Instagram app public. Click App Review left menu item and then Requests . After that follow the instructions on screen. 12.5. OpenID Connect v1.0 Identity Providers Red Hat Single Sign-On can broker identity providers based on the OpenID Connect protocol. These IDPs must support the Authorization Code Flow as defined by the specification in order to authenticate the user and authorize access. To begin configuring an OIDC provider, go to the Identity Providers left menu item and select OpenID Connect v1.0 from the Add provider drop down list. This will bring you to the Add identity provider page. Add Identity Provider The initial configuration options on this page are described in General IDP Configuration . You must define the OpenID Connect configuration options as well. They basically describe the OIDC IDP you are communicating with. Table 12.2. OpenID Connect Config Configuration Description Authorization URL Authorization URL endpoint required by the OIDC protocol. Token URL Token URL endpoint required by the OIDC protocol. Logout URL Logout URL endpoint defined in the OIDC protocol. This value is optional. Backchannel Logout Backchannel logout is a background, out-of-band, REST invocation to the IDP to logout the user. Some IDPs can only perform logout through browser redirects as they may only be able to identity sessions via a browser cookie. User Info URL User Info URL endpoint defined by the OIDC protocol. This is an endpoint from which user profile information can be downloaded. Client Authentication Switch to define the Client Authentication method to be used with the Authorization Code Flow. In the case of JWT signed with private key, the realm private key is used. In the other cases, a client secret has to be defined. For more details, see the Client Authentication specifications . Client ID This realm will act as an OIDC client to the external IDP. Your realm will need an OIDC client ID when using the Authorization Code Flow to interact with the external IDP. Client Secret This realm will need a client secret to use when using the Authorization Code Flow. The value of this field can refer a value from an external vault . Issuer Responses from the IDP may contain an issuer claim. This config value is optional. If specified, this claim will be validated against the value you provide. Default Scopes Space-separated list of OIDC scopes to send with the authentication request. The default is openid . Prompt Another optional switch. This is the prompt parameter defined by the OIDC specification. Through it you can force re-authentication and other options. See the specification for more details. Accepts prompt=none forward from client Specifies whether the IDP accepts forwarded authentication requests that contain the prompt=none query parameter or not. When a realm receives an auth request with prompt=none it checks if the user is currently authenticated and normally returns a login_required error if the user is not logged in. However, when a default IDP can be determined for the auth request (either via kc_idp_hint query param or by setting up a default IDP for the realm) we should be able to forward the auth request with prompt=none to the default IDP so that it checks if the user is currently authenticated there. Because not all IDPs support requests with prompt=none this switch is used to indicate if the default IDP supports the param before redirecting the auth request. It is important to note that if the user is not authenticated in the IDP, the client will still get a login_required error. Even if the user is currently authenticated in the IDP, the client might still get an interaction_required error if authentication or consent pages requiring user interaction would be otherwise displayed. This includes required actions (e.g. change password), consent screens and any screens set to be displayed by the first broker login flow or post broker login flow. Validate Signatures Another optional switch. This is to specify if Red Hat Single Sign-On will verify the signatures on the external ID Token signed by this identity provider. If this is on, the Red Hat Single Sign-On will need to know the public key of the external OIDC identity provider. See below for how to set it up. WARNING: For the performance purposes, Red Hat Single Sign-On caches the public key of the external OIDC identity provider. If you think that private key of your identity provider was compromised, it is obviously good to update your keys, but it's also good to clear the keys cache. See Clearing the cache section for more details. Use JWKS URL Applicable if Validate Signatures is on. If the switch is on, then identity provider public keys will be downloaded from given JWKS URL. This allows great flexibility because new keys will be always re-downloaded when the identity provider generates new keypair. If the switch is off, then public key (or certificate) from the Red Hat Single Sign-On DB is used, so whenever the identity provider keypair changes, you will always need to import the new key to the Red Hat Single Sign-On DB as well. JWKS URL URL where the identity provider JWK keys are stored. See the JWK specification for more details. If you use an external Red Hat Single Sign-On as an identity provider, then you can use URL like http://broker-keycloak:8180/auth/realms/test/protocol/openid-connect/certs assuming your brokered Red Hat Single Sign-On is running on http://broker-keycloak:8180 and it's realm is test . Validating Public Key Applicable if Use JWKS URL is off. Here is the public key in PEM format that must be used to verify external IDP signatures. Validating Public Key Id Applicable if Use JWKS URL is off. This field specifies ID of the public key in PEM format. This config value is optional. As there is no standard way for computing key ID from key, various external identity providers might use different algorithm from Red Hat Single Sign-On. If the value of this field is not specified, the validating public key specified above is used for all requests regardless of key ID sent by external IDP. When set, value of this field serves as key ID used by Red Hat Single Sign-On for validating signatures from such providers and must match the key ID specified by the IDP. You can also import all this configuration data by providing a URL or file that points to OpenID Provider Metadata (see OIDC Discovery specification). If you are connecting to a Red Hat Single Sign-On external IDP, you can import the IDP settings from the url <root>/auth/realms/{realm-name}/.well-known/openid-configuration . This link is a JSON document describing metadata about the IDP. 12.6. SAML v2.0 Identity Providers Red Hat Single Sign-On can broker identity providers based on the SAML v2.0 protocol. To begin configuring an SAML v2.0 provider, go to the Identity Providers left menu item and select SAML v2.0 from the Add provider drop down list. This will bring you to the Add identity provider page. Add Identity Provider The initial configuration options on this page are described in General IDP Configuration . You must define the SAML configuration options as well. They basically describe the SAML IDP you are communicating with. Table 12.3. SAML Config Configuration Description Service Provider Entity ID This is a required field and specifies the SAML Entity ID that the remote Identity Provider will use to identify requests coming from this Service Provider. By default it is set to the realm base URL <root>/auth/realms/{realm-name} . Single Sign-On Service URL This is a required field and specifies the SAML endpoint to start the authentication process. If your SAML IDP publishes an IDP entity descriptor, the value of this field will be specified there. Single Logout Service URL This is an optional field that specifies the SAML logout endpoint. If your SAML IDP publishes an IDP entity descriptor, the value of this field will be specified there. Backchannel Logout Enable if your SAML IDP supports backchannel logout. NameID Policy Format Specifies the URI reference corresponding to a name identifier format. Defaults to urn:oasis:names:tc:SAML:2.0:nameid-persistent . Principal Type Specifies which part of the SAML assertion will be used to identify and track external user identities. Can be either Subject NameID or SAML attribute (either by name or by friendly name). Principal Attribute If Principal is set to either "Attribute [Name]" or "Attribute [Friendly Name]", this field will specify the name or the friendly name of the identifying attribute, respectively. HTTP-POST Binding Response When this realm responds to any SAML requests sent by the external IDP, which SAML binding should be used? If set to off , then the Redirect Binding will be used. HTTP-POST Binding for AuthnRequest When this realm requests authentication from the external SAML IDP, which SAML binding should be used? If set to off , then the Redirect Binding will be used. Want AuthnRequests Signed If true, it will use the realm's keypair to sign requests sent to the external SAML IDP. Signature Algorithm If Want AuthnRequests Signed is on, then you can also pick the signature algorithm to use. SAML Signature Key Name Signed SAML documents sent via POST binding contain identification of signing key in KeyName element. This by default contains Red Hat Single Sign-On key ID. However various external SAML IDPs might expect a different key name or no key name at all. This switch controls whether KeyName contains key ID (option KEY_ID ), subject from certificate corresponding to the realm key (option CERT_SUBJECT - expected for instance by Microsoft Active Directory Federation Services), or that the key name hint is completely omitted from the SAML message (option NONE ). Force Authentication Indicates that the user will be forced to enter their credentials at the external IDP even if they are already logged in. Validate Signature Whether or not the realm should expect that SAML requests and responses from the external IDP to be digitally signed. It is highly recommended you turn this on! Validating X509 Certificate The public certificate that will be used to validate the signatures of SAML requests and responses from the external IDP. You can also import all this configuration data by providing a URL or file that points to the SAML IDP entity descriptor of the external IDP. If you are connecting to a Red Hat Single Sign-On external IDP, you can import the IDP settings from the URL <root>/auth/realms/{realm-name}/protocol/saml/descriptor . This link is an XML document describing metadata about the IDP. You can also import all this configuration data by providing a URL or XML file that points to the entity descriptor of the external SAML IDP you want to connect to. 12.6.1. SP Descriptor Once you create a SAML provider, there is an EXPORT button that appears when viewing that provider. Clicking this button will export a SAML SP entity descriptor which you can use to import into the external SP. This metadata is also available publicly by going to the URL. 12.7. Client-suggested Identity Provider OIDC applications can bypass the Red Hat Single Sign-On login page by specifying a hint on which identity provider they want to use. This is done by setting the kc_idp_hint query parameter in the Authorization Code Flow authorization endpoint. Red Hat Single Sign-On OIDC client adapters also allow you to specify this query parameter when you access a secured resource at the application. For example: In this case, it is expected that your realm has an identity provider with an alias facebook . If this provider doesn't exist the login form will be displayed. If you are using keycloak.js adapter, you can also achieve the same behavior: var keycloak = new Keycloak('keycloak.json'); keycloak.createLoginUrl({ idpHint: 'facebook' }); The kc_idp_hint query parameter also allows the client to override the default identity provider if one is configured for the Identity Provider Redirector authenticator. The client can also disable the automatic redirecting by setting the kc_idp_hint query parameter to an empty value. 12.8. Mapping Claims and Assertions You can import the SAML and OpenID Connect metadata provided by the external IDP you are authenticating with into the environment of the realm. This allows you to extract user profile metadata and other information so that you can make it available to your applications. Each new user that logs into your realm via an external identity provider will have an entry for them created in the local Red Hat Single Sign-On database, based on the metadata from the SAML or OIDC assertions and claims. If you click on an identity provider listed in the Identity Providers page for your realm, you will be brought to the IDPs Settings tab. On this page there is also a Mappers tab. Click on that tab to start mapping your incoming IDP metadata. There is a Create button on this page. Clicking on this create button allows you to create a broker mapper. Broker mappers can import SAML attributes or OIDC ID/Access token claims into user attributes and user role mappings. Select a mapper from the Mapper Type list. Hover over the tooltip to see a description of what the mapper does. The tooltips also describe what configuration information you need to enter. Click Save and your new mapper will be added. For JSON based claims, you can use dot notation for nesting and square brackets to access array fields by index. For example 'contact.address[0].country'. To investigate the structure of user profile JSON data provided by social providers you can enable the DEBUG level logger org.keycloak.social.user_profile_dump . This is done in the server's app-server configuration file (domain.xml or standalone.xml). 12.9. Available User Session Data After a user logs in from the external IDP, there is some additional user session note data that Red Hat Single Sign-On stores that you can access. This data can be propagated to the client requesting a login via the token or SAML assertion being passed back to it by using an appropriate client mapper. identity_provider This is the IDP alias of the broker used to perform the login. identity_provider_identity This is the IDP username of the currently authenticated user. This is often the same as the Red Hat Single Sign-On username, but doesn't necessarily needs to be. For example Red Hat Single Sign-On user john can be linked to the Facebook user john123@gmail.com , so in that case value of user session note will be john123@gmail.com . You can use a Protocol Mapper of type User Session Note to propagate this information to your clients. 12.10. First Login Flow When a user logs in through identity brokering some aspects of the user are imported and linked within the realm's local database. When Red Hat Single Sign-On successfully authenticates users through an external identity provider there can be two situations: There is already a Red Hat Single Sign-On user account imported and linked with the authenticated identity provider account. In this case, Red Hat Single Sign-On will just authenticate as the existing user and redirect back to application. There is not yet an existing Red Hat Single Sign-On user account imported and linked for this external user. Usually you just want to register and import the new account into Red Hat Single Sign-On database, but what if there is an existing Red Hat Single Sign-On account with the same email? Automatically linking the existing local account to the external identity provider is a potential security hole as you can't always trust the information you get from the external identity provider. Different organizations have different requirements when dealing with some of the conflicts and situations listed above. For this, there is a First Login Flow option in the IDP settings which allows you to choose a workflow that will be used after a user logs in from an external IDP the first time. By default it points to first broker login flow, but you can configure and use your own flow and use different flows for different identity providers. The flow itself is configured in admin console under Authentication tab. When you choose First Broker Login flow, you will see what authenticators are used by default. You can re-configure the existing flow. (For example you can disable some authenticators, mark some of them as required , configure some authenticators, etc). 12.10.1. Default First Login Flow Let's describe the default behavior provided by First Broker Login flow. Review Profile This authenticator might display the profile info page, where the user can review their profile retrieved from an identity provider. The authenticator is configurable. You can set the Update Profile On First Login option. When On , users will be always presented with the profile page asking for additional information in order to federate their identities. When missing , users will be presented with the profile page only if some mandatory information (email, first name, last name) is not provided by the identity provider. If Off , the profile page won't be displayed, unless user clicks in later phase on Review profile info link (page displayed in later phase by Confirm Link Existing Account authenticator). Create User If Unique This authenticator checks if there is already an existing Red Hat Single Sign-On account with the same email or username like the account from the identity provider. If it's not, then the authenticator just creates a new local Red Hat Single Sign-On account and links it with the identity provider and the whole flow is finished. Otherwise it goes to the Handle Existing Account subflow. If you always want to ensure that there is no duplicated account, you can mark this authenticator as REQUIRED . In this case, the user will see the error page if there is an existing Red Hat Single Sign-On account and the user will need to link his identity provider account through Account management. Confirm Link Existing Account On the info page, the user will see that there is an existing Red Hat Single Sign-On account with the same email. They can review their profile again and use different email or username (flow is restarted and goes back to Review Profile authenticator). Or they can confirm that they want to link their identity provider account with their existing Red Hat Single Sign-On account. Disable this authenticator if you don't want users to see this confirmation page, but go straight to linking identity provider account by email verification or re-authentication. Verify Existing Account By Email This authenticator is ALTERNATIVE by default, so it's used only if the realm has SMTP setup configured. It will send email to the user, where they can confirm that they want to link the identity provider with their Red Hat Single Sign-On account. Disable this if you don't want to confirm linking by email, but instead you always want users to reauthenticate with their password (and alternatively OTP). Verify Existing Account By Re-authentication This authenticator is used if email authenticator is disabled or not available (SMTP not configured for realm). It will display a login screen where the user needs to authenticate to link their Red Hat Single Sign-On account with the Identity provider. User can also re-authenticate with some different identity provider, which is already linked to their Red Hat Single Sign-On account. You can also force users to use OTP. Otherwise it's optional and used only if OTP is already set for the user account. 12.10.2. Automatically Link Existing First Login Flow Warning The AutoLink authenticator would be dangerous in a generic environment where users can register themselves using arbitrary usernames/email addresses. Do not use this authenticator unless registration of users is carefully curated and usernames/email addresses are assigned, not requested. In order to configure a first login flow in which users are automatically linked without being prompted, create a new flow with the following two authenticators: Create User If Unique This authenticator ensures that unique users are handled. Set the authenticator requirement to "Alternative". Automatically Set Existing User Automatically sets an existing user to the authentication context without any verification. Set the authenticator requirement to "Alternative". Note The described setup uses two authenticators. This setup is the simplest one, but it is possible to use other authenticators according to your needs. For example, you can add the Review Profile authenticator to the beginning of the flow if you still want end users to confirm their profile information. You can also add authentication mechanisms to this flow, forcing a user to verify his credentials. This would require a more complex flow, for example setting the "Automatically Set Existing User" and "Password Form" as "Required" in an "Alternative" sub-flow. 12.10.3. Disabling Automatic User Creation The Default first login flow will look up a Keycloak account matching the external identity, and will then offer to link them; if there is no matching Keycloak account, it will automatically create one. This default behavior may be unsuitable for some setups, for example, when using read-only LDAP user store (which means all users are pre-created). In this case, automatic user creation should be turned off. To disable user creation: open the First Broker Login flow configuration; set Create User If Unique to DISABLED ; set Confirm Link Existing Account to DISABLED . This configuration also implies that Keycloak itself won't be able to determine which internal account would correspond to the external identity. Therefore, the Verify Existing Account By Re-authentication authenticator will ask the user to provide both username and password. 12.11. Retrieving External IDP Tokens Red Hat Single Sign-On allows you to store tokens and responses from the authentication process with the external IDP. For that, you can use the Store Token configuration option on the IDP's settings page. Application code can retrieve these tokens and responses to pull in extra user information, or to securely invoke requests on the external IDP. For example, an application might want to use the Google token to invoke on other Google services and REST APIs. To retrieve a token for a particular identity provider you need to send a request as follows: An application must have authenticated with Red Hat Single Sign-On and have received an access token. This access token will need to have the broker client-level role read-token set. This means that the user must have a role mapping for this role and the client application must have that role within its scope. In this case, given that you are accessing a protected service in Red Hat Single Sign-On, you need to send the access token issued by Red Hat Single Sign-On during the user authentication. In the broker configuration page you can automatically assign this role to newly imported users by turning on the Stored Tokens Readable switch. These external tokens can be re-established by either logging in again through the provider, or using the client-initiated account linking API. 12.12. Identity broker logout When logout from Red Hat Single Sign-On is triggered, Red Hat Single Sign-On will send a request to the external identity provider that was used to login to Keycloak, and the user will be logged out from this identity provider as well. It is possible to skip this behavior and avoid logout at the external identity provider. See adapter logout documentation for more details.

Commands:
oc create -f <(echo ' kind: OAuthClient apiVersion: v1 metadata: name: kc-client 1 secret: "..." 2 redirectURIs: - "http://www.example.com/" 3 grantMethod: prompt 4 ')
oc create -f <(echo ' kind: OAuthClient apiVersion: v1 metadata: name: keycloak-broker 1 secret: "..." 2 redirectURIs: - "<copy pasted Redirect URI from OpenShift 4 Identity Providers page>" 3 grantMethod: prompt 4 ')
http[s]://{host:port}/auth/realms/{realm-name}/broker/{broker-alias}/endpoint/descriptor
GET /myapplication.com?kc_idp_hint=facebook HTTP/1.1 Host: localhost:8080
var keycloak = new Keycloak('keycloak.json'); keycloak.createLoginUrl({ idpHint: 'facebook' });
GET /auth/realms/{realm}/broker/{provider_alias}/token HTTP/1.1 Host: localhost:8080 Authorization: Bearer <KEYCLOAK ACCESS TOKEN>