keycloak-scim/docbook/reference/en/en-US/modules/identity-broker.xml

<chapter id="identity-broker">
    <title>Identity Broker</title>

    <para>
        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 to create a trust relationship with an external
        identity provider in order to use its identities to access internal services exposed by service providers.
    </para>

    <para>
        From an user perspective, an identity broker provides an user-centric and centralized way to manage identities across
        different security domains or realms, where 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.
    </para>

    <para>
        An identity provider is usually based on a specific protocol in order to authenticate and communicate authentication and
        authorization information to their users. It can be a social provider such as Facebook, Google or Twitter, a business partner
        which you want to allow its users to access your services or a cloud-based identity service that you want to integrate with.
        Usually, identity providers are based on the following protocols:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <literal>SAML v2.0</literal>
            </para>
        </listitem>
        <listitem>
            <para>
                <literal>OpenID Connect v1.0</literal>
            </para>
        </listitem>
        <listitem>
            <para>
                <literal>oAuth v2.0</literal>
            </para>
        </listitem>
    </itemizedlist>

    <para>
        In the next sections we'll see how to configure and use Keycloak as an identity broker, covering some important aspects such as:
    </para>

    <itemizedlist>
        <listitem>
            <para>
                <literal>Social Authentication</literal>
            </para>
        </listitem>
        <listitem>
            <para>
                <literal>OpenID Connect v1.0 Brokering</literal>
            </para>
        </listitem>
        <listitem>
            <para>
                <literal>SAML v2.0 Brokering</literal>
            </para>
        </listitem>
        <listitem>
            <para>
                <literal>Identity Federation</literal>
            </para>
        </listitem>

    </itemizedlist>

    <section>
        <title>Overview</title>

        <para>
            When using Keycloak as an identity broker, users are not forced to provide their credentials in order to
            authenticate in a specific realm. Instead of that, they are presented with a list of identity providers from
            where they can pick one and authenticate. You can also configure a hard-coded default broker.  In this case
            the user will not be given a choice, but instead be redirected directly the the parent broker.
            The following diagram demonstrates the steps involved when using
            Keycloak to broker an external identity provider:
        </para>

        <para>
        	<imagedata fileref="images/identity_broker_flow.png"/>
        </para>

        <orderedlist>
            <listitem>
                <para>
                    User is not authenticated and requests a protected resource in a service provider.
                </para>
            </listitem>
            <listitem>
                <para>
                    The service provider redirects the user to Keycloak to authenticate.
                </para>
            </listitem>
            <listitem>
                <para>
                    At this point the user is presented to the login page where there is a list of identity providers supported by a realm.
                </para>
            </listitem>
            <listitem>
                <para>
                    User selects one of the identity providers by clicking on its respective button or link.
                </para>
            </listitem>
            <listitem>
                <para>
                    Keycloak issues an authentication request to the target identity provider asking for authentication and the
                    user is redirect to the login page or just to a consent page in the identity provider.
                    The connection properties and other configuration options for the identity provider were previously
                    set by the administrator in the admin console.
                </para>
            </listitem>
            <listitem>
                <para>
                    User provides his credentials or consent in order to authenticate in the identity provider.
                </para>
            </listitem>
            <listitem>
                <para>
                    Upon a successful authentication by the identity provider, the user is redirected back to Keycloak
                    with an authentication response. Usually this response contains a security token that will be used
                    by Keycloak to trust the authentication performed by the identity provider and retrieve information
                    about the user.
                </para>
            </listitem>
            <listitem>
                <para>
                    Now Keycloak is going to check if the response from the identity provider is valid. If valid, it will create an user
                    or just skip that if the user already exists. If it is a new user, Keycloak will ask informations about the user to the identity provider
                    (or just read that from a security token) and create the user locally. This is what we call <emphasis>identity federation</emphasis>.
                    If the user already exists Keycloak will ask him to link the identity returned from the identity provider
                    with his existing account. A process that we call <emphasis>account linking</emphasis>.
                    At the end of this step, Keycloak authenticates the user and issues its own token in order to access
                    the requested resource in the service provider.
                </para>
            </listitem>
            <listitem>
                <para>
                    Once the user is locally authenticated, Keycloak redirects the user to the service provider by sending
                    the token previously issued during the local authentication.
                </para>
            </listitem>
            <listitem>
                <para>
                    The service provider receives the token from Keycloak and allows access to the protected resource.
                </para>
            </listitem>
        </orderedlist>

        <para>
            There are some variations of this flow that we will talk about later. For instance, instead of present a
            list of identity providers, the service provider can automatically select a specific one to authenticate an user.
            Or you can tell Keycloak to force the user to provide additional information before federate his identity.
        </para>

        <note>
            <para>
                Different protocols may require different authentication flows. At this moment, all the identity providers
                supported by KeyCloak use a flow just like described above. However, despite the protocol in use, user experience should
                be pretty much the same.
            </para>
        </note>

        <para>
            As you may notice, at the end of the authentication process Keycloak will always issue its own token
            to service providers, what means that service providers 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 Keycloak !
        </para>
    </section>

    <section>
        <title>Configuration</title>
        <para>
            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.
        </para>
        <para>
            In order to create an identity provider, follow these steps:
        </para>
        <orderedlist>
            <listitem>
                <para>In the admin console, select a realm.</para>
            </listitem>
            <listitem>
                <para>On the left side menu, click on <literal>Settings</literal>.</para>
            </listitem>
            <listitem>
                <para>
                    Select the <literal>Identity Provider</literal> tab on the settings page.
                </para>
            </listitem>
            <listitem>
                <para>
                    You should now be able to see a table that lists all registered identity providers.
                    To add a new identity provider, click the select box on the top right of this table and select
                    which type of identity provider you want to create.
                </para>
            </listitem>
        </orderedlist>
        <para>
            Identity providers are organized in two main categories:
        </para>
        <variablelist>
            <varlistentry>
                <term>Social</term>
                <listitem>
                    <para>
                        Social providers allows you to enable social authentication to your realm.
                        Keycloak makes it easy to let users log in to your application using an existing account with a social network.
                        Currently Facebook, Google and Twitter are supported with more planned for the future.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Protocol-based</term>
                <listitem>
                    <para>
                        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.
                        Keycloak 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.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
        <para>
            Although each type of identity provider has its own configuration options, all of them share some very common configuration.
            Regardless the identity provider you are creating, you'll see the following configuration options avaiable:
        </para>
        <table>
            <title>Common Configuration</title>
            <tgroup align="left" cols="2">
                <thead>
                    <row>
                        <entry>
                            Configuration
                        </entry>
                        <entry>
                            Description
                        </entry>
                    </row>
                </thead>
                <tbody valign="top">
                    <row>
                        <entry>
                            <literal>Alias</literal>
                        </entry>
                        <entry>
                            The alias is an unique identifier for an identity provider. It is used to reference internally an identity provider.
                            Some protocols require a <emphasis>redirect uri or callback url</emphasis> in order to communicate with an identity provider. For instance, OpenID Connect.
                            In this case, the alias is used to build the redirect uri.
                            Every single identity provider must have an alias. For example, facebook, google, idp.acme.com, etc.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <literal>Name</literal>
                        </entry>
                        <entry>
                            You can give a friendly name to an identity provider.
                            The name will be used, for example, to display a link or a button in the login page.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <literal>Enabled</literal>
                        </entry>
                        <entry>
                            Allows you to enable or disable an identity provider.
                            When disabled, the identity provider will not be available from the login page and can not
                            be used by any other means.
                        </entry>
                    </row>
                   <row>
                        <entry>
                            <literal>Store Tokens</literal>
                        </entry>
                        <entry>
                            Any external tokens provided by the parent IDP will be stored.
                            This options is useful if you are using social authentication and need to access the token in order to invoke the
                            API of a social provider on behalf of the user.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <literal>Stored Tokens Readable</literal>
                        </entry>
                        <entry>
                            Automatically assigns a <literal>broker.read-token</literal> role that allows the user
                            to access any stored external tokens via the broker service.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <literal>Update Profile on First Login</literal>
                        </entry>
                        <entry>
                            Allows you to force users to update their profile right after the authentication finishes and
                            before the account is actually created in Keycloak. When enabled, users will be presented with the
                            <emphasis>update profile page</emphasis> asking for additional information in order to federate their identities.
                            If disabled, the account will be created with the minimal information obtained from the identity provider
                            during the authentication process.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <literal>GUI order</literal>
                        </entry>
                        <entry>
                            Allows you to define order of the provider when shown on login page. 
                            You can put number into this field, providers with lower numbers are shown first.
                        </entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
        <para>
            On the next sections, we'll see how to configure each type of identity provider individually.
        </para>
    </section>

    <section>
        <title>Social Identity Providers</title>
        <para>
            Forcing users to register to your realm when they want to access applications is hard.
            So is trying to remember yet another username and password combination.
            Social identity providers makes it easy for users to register on your realm and quickly sign in using a social network.
            Keycloak provides built-in support for the most common social networks out there, such as Google, Facebook, Twitter and
            even Github.
        </para>

        <section>
            <title>Google</title>
            <para>
                To enable login with Google you first have to create a project and a client in the
                <ulink url="https://cloud.google.com/console/project">Google Developer Console</ulink>. Then you need to copy
                the client id and secret into the Keycloak Admin Console.
            </para>
            <para>
                Let's see first how to create a project with Google.
            </para>
            <orderedlist>
                <listitem>
                    <para>
                        Log in to the <ulink url="https://cloud.google.com/console/project">Google Developer Console</ulink>. Click the
                        <literal>Create Project</literal> button. Use any value for <literal>Project name</literal> and
                        <literal>Project ID</literal> you want, then click the <literal>Create</literal> button. Wait for the project to
                        be created (this may take a while).
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Once the project has been created click on <literal>APIs &amp; auth</literal> in sidebar on the left. To retrieve
                        user profiles the <literal>Google+ API</literal> has to be enabled. Scroll down to find it in the list. If its
                        status is <literal>OFF</literal>, click on <literal>OFF</literal> to enable it (it should move to the top of
                        the list and the status should be <literal>ON</literal>).
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Now click on the <literal>Consent screen</literal> link on the sidebar menu on the left.  You must specify
                        a project name and choose an email for the consent screen.  Otherwise users will get a login error.  There's
                        other things you can configure here like what the consent screen looks like.  Feel free to play around with this.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Now click <literal>Credentials</literal> in the sidebar on the left. Then click
                        <literal>Create New Client ID</literal>. Select <literal>Web application</literal> as
                        <literal>Application type</literal>. Empty the <literal>Authorized Javascript origins</literal> textarea.
                        Click the <literal>Create Client ID</literal> button.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Copy <literal>Client ID</literal> and <literal>Client secret</literal>.
                    </para>
                </listitem>
            </orderedlist>
            <para>
                Now that you have the client id and secret, you can proceed with the creation of a Google Identity Provider in Keycloak. As follows:
            </para>
            <orderedlist>
                <listitem>
                    <para>
                        Select the <literal>Google</literal> identity provider from the drop-down box on the top right corner of the identity providers table in Keycloak's Admin Console. You should be presented with a specific page to configure the selected provided.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Copy the client id and secret to their corresponding fields in the Keycloak Admin Console. Click <literal>Save</literal>.
                    </para>
                </listitem>
            </orderedlist>
            <para>
                Once you create the identity provider in Keycloak, you must update your Google project with the redirect url that was
                generated to your identity provider.
            </para>
            <orderedlist>
                <listitem>
                    <para>
                        Open the Google Developer Console and select your project. Click <literal>Credentials</literal> in the
                        sidebar on the left. In <literal>Authorized redirect URI</literal> insert the redirect uri created by Keycloak. The redirect uri
                        usually have the following format: <literal>http://{host}:{port}/auth/realms/{realm}/broker/{provider_alias}</literal>.
                    </para>
                </listitem>
            </orderedlist>
            <note>
                <para>
                    You can always get the redirect url for a specific identity provider from the table presented when you
                    click on the 'Identity Provider' tab in <emphasis>Realm > Settings</emphasis>.
                </para>
            </note>
            <para>
                That is it! This is pretty much what you need to do in order to setup this identity provider.
            </para>
            <para>
                The table below lists some additional configuration options you may use when configuring this provider.
            </para>
            <table>
                <title>Configuration Options</title>
                <tgroup align="left" cols="2">
                    <thead>
                        <row>
                            <entry>
                                Configuration
                            </entry>
                            <entry>
                                Description
                            </entry>
                        </row>
                    </thead>
                    <tbody valign="top">
                        <row>
                            <entry>
                                <literal>Default Scopes</literal>
                            </entry>
                            <entry>
                                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 <ulink url="https://developers.google.com/oauthplayground/">https://developers.google.com/oauthplayground/</ulink>. By default, Keycloak uses the following scopes: <literal>openid profile email</literal>
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </section>
        <section>
            <title>Facebook</title>
            <para>
                To enable login with Facebook you first have to create an application in the
                <ulink url="https://developers.facebook.com/">Facebook Developer Console</ulink>. Then you need to copy
                the client id and secret into the Keycloak Admin Console.
            </para>
            <para>
                Let's see first how to create an application with Facebook.
            </para>
            <orderedlist>
                <listitem>
                    <para>
                        Log in to the <ulink url="https://developers.facebook.com/">Facebook Developer Console</ulink>. Click
                        <literal>Apps</literal> in the menu and select <literal>Create a New App</literal>. Use any value for
                        <literal>Display Name</literal> and <literal>Category</literal> you want, then click the
                        <literal>Create App</literal> button. Wait for the project to be created (this may take a while). If after
                        creating the app you are not redirected to the app settings, click on <literal>Apps</literal> in the
                        menu and select the app you created.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Once the app has been created click on <literal>Settings</literal> in sidebar on the left. You must specify
                        a contact email.  Save your changes.  Then click
                        on <literal>Advanced</literal>. Under <literal>Security</literal> make sure
                        <literal>Client OAuth Login</literal> is enabled. Scroll down and click on the <literal>Save Changes</literal> button.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Click <literal>Status &amp; Review</literal> and select <literal>YES</literal> for <literal>Do you want
                        to make this app and all its live features available to the general public?</literal>.  You will
                        not be able to set this until you have provided a contact email in the general settings of this application.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Click <literal>Basic</literal>. Copy <literal>App ID</literal> and <literal>App Secret</literal>
                        (click <literal>show</literal>) from the <ulink url="https://developers.facebook.com/">Facebook Developer Console</ulink>.
                    </para>
                </listitem>
            </orderedlist>
            <para>
                Now that you have the client id and secret, you can proceed with the creation of a Facebook Identity Provider in Keycloak. As follows:
            </para>
            <orderedlist>
                <listitem>
                    <para>
                        Select the <literal>Facebook</literal> identity provider from the drop-down box on the top right corner of the identity providers table in Keycloak's Admin Console. You should be presented with a specific page to configure the selected provided.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Copy the client id and secret to their corresponding fields in the Keycloak Admin Console. Click <literal>Save</literal>.
                    </para>
                </listitem>
            </orderedlist>
            <para>
                Once you create the identity provider in Keycloak, you must update your Facebook application with the redirect url that was
                generated to your identity provider.
            </para>
            <orderedlist>
                <listitem>
                    <para>
                        Open the Facebook Developer Console and select your application. Click
                        on <literal>Advanced</literal>. Under <literal>Security</literal> make sure
                        <literal>Client OAuth Login</literal> is enabled. In <literal>Valid OAuth redirect URIs</literal> insert
                        the redirect uri created by Keycloak. The redirect uri
                        usually have the following format: <literal>http://{host}:{port}/auth/realms/{realm}/broker/{provider_alias}</literal>.
                    </para>
                </listitem>
            </orderedlist>
            <note>
                <para>
                    You can always get the redirect url for a specific identity provider from the table presented when you
                    click on the 'Identity Provider' tab in <emphasis>Realm > Settings</emphasis>.
                </para>
            </note>
            <para>
                That is it! This pretty much what you need to do in order to setup this identity 		provider.
            </para>
            <para>
                The table below lists some additional configuration options you may use when configuring this provider.
            </para>
            <table>
                <title>Configuration Options</title>
                <tgroup align="left" cols="2">
                    <thead>
                        <row>
                            <entry>
                                Configuration
                            </entry>
                            <entry>
                                Description
                            </entry>
                        </row>
                    </thead>
                    <tbody valign="top">
                        <row>
                            <entry>
                                <literal>Default Scopes</literal>
                            </entry>
                            <entry>
                                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 <ulink url="https://developers.facebook.com/docs/graph-api">https://developers.facebook.com/docs/graph-api</ulink>. By default, Keycloak uses the following scopes: <literal>email</literal>
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </section>
        <section>
            <title>Twitter</title>
            <para>
                To enable login with Twtter you first have to create an application in the
                <ulink url="https://dev.twitter.com/apps">Twitter Developer Console</ulink>. Then you need to copy
                the consumer key and secret into the Keycloak Admin Console.
            </para>
            <para>
                Let's see first how to create an application with Twitter.
            </para>
            <orderedlist>
                <listitem>
                    <para>
                        Log in to the <ulink url="https://dev.twitter.com/apps">Twitter Developer Console</ulink>. Click the
                        <literal>Create a new application</literal> button. Use any value for <literal>Name</literal>,
                        <literal>Description</literal> and <literal>Website</literal> you want. Insert the social callback url
                        in <literal>Callback URL</literal>. Then click <literal>Create your Twitter application</literal>.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Now click on <literal>Settings</literal> and tick the box <literal>Allow this application to be used to Sign in with Twitter</literal>,
                        then click on <literal>Update this Twitter application's settings</literal>.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Now click <literal>API Keys</literal> tab. Copy <literal>API key</literal> and <literal>API secret</literal> from the
                        <ulink url="https://dev.twitter.com/apps">Twitter Developer Console</ulink>.
                    </para>
                </listitem>
            </orderedlist>
            <note>
                <para>
                    Twitter doesn't allow <literal>localhost</literal> in the redirect URI. To test on a local server
                    replace <literal>localhost</literal> with <literal>127.0.0.1</literal>.
                </para>
            </note>

            <para>
                Now that you have the client id and secret, you can proceed with the creation of a Twitter Identity Provider in Keycloak. As follows:
            </para>
            <orderedlist>
                <listitem>
                    <para>
                        Select the <literal>Twitter</literal> identity provider from the drop-down box on the top right corner of the identity providers table in Keycloak's Admin Console. You should be presented with a specific page to configure the selected provided.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Copy the client id and secret to their corresponding fields in the Keycloak Admin Console. Click <literal>Save</literal>.
                    </para>
                </listitem>
            </orderedlist>
            <para>
                That is it! This pretty much what you need to do in order to setup this identity 		provider.
            </para>
            <para>
                The table below lists some additional configuration options you may use when configuring this provider.
            </para>
            <table>
                <title>Configuration Options</title>
                <tgroup align="left" cols="2">
                    <thead>
                        <row>
                            <entry>
                                Configuration
                            </entry>
                            <entry>
                                Description
                            </entry>
                        </row>
                    </thead>
                    <tbody valign="top">
                        <row>
                            <entry>
                                <literal>Default Scopes</literal>
                            </entry>
                            <entry>
                                Not supported by Twitter.
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </section>
        <section>
            <title>Github</title>
            <para>
                To enable login with GitHub you first have to create an application in
                <ulink url="https://github.com/settings/applications">GitHub Settings</ulink>. Then you need to copy
                the client id and secret into the Keycloak Admin Console.
            </para>
            <para>
                Let's see first how to create an application with GitHub.
            </para>
            <orderedlist>
                <listitem>
                    <para>
                        Log in to <ulink url="https://github.com/settings/applications">GitHub Settings</ulink>. Click the
                        <literal>Register new application</literal> button. Use any value for <literal>Application name</literal>,
                        <literal>Homepage URL</literal> and <literal>Application Description</literal> you want. Click the
                        <literal>Register application</literal> button.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Copy <literal>Client ID</literal> and <literal>Client Secret</literal> from the <ulink url="https://github.com/settings/applications">GitHub Settings</ulink>.
                    </para>
                </listitem>
            </orderedlist>
            <para>
                Now that you have the client id and secret, you can proceed with the creation of a Github Identity Provider in Keycloak. As follows:
            </para>
            <orderedlist>
                <listitem>
                    <para>
                        Select the <literal>Github</literal> identity provider from the drop-down box on the top right corner of the identity providers table in Keycloak's Admin Console. You should be presented with a specific page to configure the selected provided.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Copy the client id and secret to their corresponding fields in the Keycloak Admin Console. Click <literal>Save</literal>.
                    </para>
                </listitem>
            </orderedlist>
            <para>
                Once you create the identity provider in Keycloak, you must update your GitHub application with the redirect url that was
                generated to your identity provider.
            </para>
            <orderedlist>
                <listitem>
                    <para>
                        Open the GitHub Settings and select your application. In <literal>Authorization callback URL</literal>
                        insert the redirect uri created by Keycloak. The redirect uri
                        usually have the following format: <literal>http://{host}:{port}/auth/realms/{realm}/broker/{provider_alias}</literal>.
                    </para>
                </listitem>
            </orderedlist>
            <note>
                <para>
                    You can always get the redirect url for a specific identity provider from the table presented when you
                    click on the 'Identity Provider' tab in <emphasis>Realm > Settings</emphasis>.
                </para>
            </note>
            <para>
                That is it! This pretty much what you need to do in order to setup this identity 		provider.
            </para>
            <para>
                The table below lists some additional configuration options you may use when configuring this provider.
            </para>
            <table>
                <title>Configuration Options</title>
                <tgroup align="left" cols="2">
                    <thead>
                        <row>
                            <entry>
                                Configuration
                            </entry>
                            <entry>
                                Description
                            </entry>
                        </row>
                    </thead>
                    <tbody valign="top">
                        <row>
                            <entry>
                                <literal>Default Scopes</literal>
                            </entry>
                            <entry>
                                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 <ulink url="https://developer.github.com/v3/oauth/#scopes">https://developer.github.com/v3/oauth/#scopes</ulink>. By default, Keycloak uses the following scopes: <literal>user:email</literal>
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </section>
        <section>
            <title>LinkedIn</title>
            <para>
                To enable login with LinkedIn you first have to create an application in
                <ulink url="https://www.linkedin.com/secure/developer">LinkedIn Developer Network</ulink>. Then you need to copy
                the client id and secret into the Keycloak Admin Console.
            </para>
            <para>
                Let's see first how to create an application with LinkedIn.
            </para>
            <orderedlist>
                <listitem>
                    <para>
                        Log in to <ulink url="https://www.linkedin.com/secure/developer">LinkedIn Developer Network</ulink>. Click the
                        <literal>Add New Application</literal> link. Use any value for <literal>Application Name</literal>,
                        <literal>Website URL</literal>, <literal>Description</literal>, <literal>Developer Contact Email</literal> and <literal>Phone</literal> you want.
                        Select <literal>r_basicprofile</literal> and <literal>r_emailaddress</literal> in the <literal>Default Scope</literal> section. 
                        Click the <literal>Add Application</literal> button.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Copy <literal>Consumer Key / API Key</literal> and <literal>Consumer Secret / Secret Key</literal> from the shown page.
                    </para>
                </listitem>
            </orderedlist>
            <para>
                Now that you have the client id and secret, you can proceed with the creation of a LinkedIn Identity Provider in Keycloak. As follows:
            </para>
            <orderedlist>
                <listitem>
                    <para>
                        Select the <literal>LinkedIn</literal> identity provider from the drop-down box on the top right corner of the identity providers table in Keycloak's Admin Console. You should be presented with a specific page to configure the selected provided.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Copy the client id and secret to their corresponding fields in the Keycloak Admin Console. Click <literal>Save</literal>.
                    </para>
                </listitem>
            </orderedlist>
            <para>
                Once you create the identity provider in Keycloak, you must update your LinkedIn application with the redirect url that was
                generated to your identity provider.
            </para>
            <orderedlist>
                <listitem>
                    <para>
                        Open the LinkedIn Developer Network and select your application. In <literal>OAuth 2.0 Redirect URLs</literal>
                        insert the redirect uri created by Keycloak. The redirect uri
                        usually have the following format: <literal>http://{host}:{port}/auth/realms/{realm}/broker/{provider_alias}/endpoint</literal>.
                    </para>
                </listitem>
            </orderedlist>
            <note>
                <para>
                    You can always get the redirect url for a specific identity provider from the table presented when you
                    click on the 'Identity Provider' tab in <emphasis>Realm > Settings</emphasis>.
                </para>
            </note>
            <para>
                That is it! This pretty much what you need to do in order to setup this identity provider.
            </para>
            <para>
                The table below lists some additional configuration options you may use when configuring this provider.
            </para>
            <table>
                <title>Configuration Options</title>
                <tgroup align="left" cols="2">
                    <thead>
                        <row>
                            <entry>
                                Configuration
                            </entry>
                            <entry>
                                Description
                            </entry>
                        </row>
                    </thead>
                    <tbody valign="top">
                        <row>
                            <entry>
                                <literal>Default Scopes</literal>
                            </entry>
                            <entry>
                                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 application configuration in <ulink url="https://www.linkedin.com/secure/developer">LinkedIn Developer Network</ulink>. By default, Keycloak uses the following scopes: <literal>r_basicprofile r_emailaddress</literal>
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </section>
        <section>
            <title>StackOverflow</title>
            <para>
                To enable login with StackOverflow you first have to register an OAuth application on
                <ulink url="https://stackapps.com/">StackApps</ulink>. Then you need to copy the client id, secret and key into the Keycloak Admin Console.
            </para>
            <para>
                Let's see first how to create an application with StackOverflow.
            </para>
            <orderedlist>
                <listitem>
                    <para>
                        Go to <ulink url="http://stackapps.com/apps/oauth/register">registering your application on Stack Apps</ulink> url and login here. 
                        Use any value for <literal>Application Name</literal>, <literal>Application Website</literal> and <literal>Description</literal> you want.
                        Set <literal>OAuth Domain</literal> to the domain where your Keycloak instance runs.
                        Click the <literal>Register Your Application</literal> button.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Copy <literal>Client Id</literal>, <literal>Client Secret</literal> and <literal>Key</literal> from the shown page.
                    </para>
                </listitem>
            </orderedlist>
            <para>
                Now that you have the client id, secret and key, you can proceed with the creation of a StackOverflow Identity Provider in Keycloak. As follows:
            </para>
            <orderedlist>
                <listitem>
                    <para>
                        Select the <literal>StackOverflow</literal> identity provider from the drop-down box on the top right corner of the identity providers table in Keycloak's Admin Console. You should be presented with a specific page to configure the selected provided.
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Copy the client id, client secret and key to their corresponding fields in the Keycloak Admin Console. Click <literal>Save</literal>.
                    </para>
                </listitem>
            </orderedlist>
            <para>
                That is it! This pretty much what you need to do in order to setup this identity provider.
            </para>
            <para>
                The table below lists some additional configuration options you may use when configuring this provider.
            </para>
            <table>
                <title>Configuration Options</title>
                <tgroup align="left" cols="2">
                    <thead>
                        <row>
                            <entry>
                                Configuration
                            </entry>
                            <entry>
                                Description
                            </entry>
                        </row>
                    </thead>
                    <tbody valign="top">
                        <row>
                            <entry>
                                <literal>Default Scopes</literal>
                            </entry>
                            <entry>
                                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 application configuration in <ulink url="https://api.stackexchange.com/docs/authentication#scope">StackExchange API Authentication</ulink> documentation. Keycloak uses the empty scope by default.
                            </entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>
        </section>        
    </section>

    <section>
        <title>SAML v2.0 Identity Providers</title>
        <para>
            Keycloak can broker identity providers based on the SAML v2.0 protocol.
        </para>
        <para>
            In order to configure a SAML identity provider, follow these steps:
        </para>
        <orderedlist>
            <listitem>
                <para>
                    Select the <literal>SAML v2.0</literal> identity provider from the drop-down box on the top right
                    corner of the identity providers table in Keycloak's Admin Console.
                    You should be presented with a specific page to configure the selected provider.
                </para>
            </listitem>
        </orderedlist>
        <para>
            When configuring a SAML identity provider you are presented with different configuration options in order to
            properly communicate and integrate with the external identity provider.
            In this case, you must keep in mind that Keycloak will act as an Service Provider that issues authentication requests(AuthnRequest)
            to the external identity provider.
        </para>
        <table>
            <title>Configuration Options</title>
            <tgroup align="left" cols="2">
                <thead>
                    <row>
                        <entry>
                            Configuration
                        </entry>
                        <entry>
                            Description
                        </entry>
                    </row>
                </thead>
                <tbody valign="top">
                    <row>
                        <entry>
                            <literal>Import IdP SAML Metadata</literal>
                        </entry>
                        <entry>
                            When creating a new identity provider, you may just upload the SAML Metadata for the brokered IdP (IDPSSODescriptor). In this case, Keycloak will read all the necessary configuration from the metadata and automatically configure the identity provider for you.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <literal>Single Sign-On Service Url</literal>
                        </entry>
                        <entry>
                            Allows you to specify the URL that will be used to send SAML authentication requests.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <literal>Single Logout Service Url</literal>
                        </entry>
                        <entry>
                            Allows you to specify the URL that will be used to send SAML logout requests.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <literal>Backchannel Logout</literal>
                        </entry>
                        <entry>
                            If set to true, logout to the external IDP will be done in a background HTTP request.  If
                            set to false, then the browser will be redirected to the external IDP to perform the logout.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <literal>NameID Policy Format</literal>
                        </entry>
                        <entry>
                            Allows you to specify a NameID Policy that will be sent in the SAML authentication request.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <literal>Validating X509 Certificate</literal>
                        </entry>
                        <entry>
                            Allows you to specify the certificate in PEM format that will be used to validate signatures for all messages received from the brokered identity provider.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <literal>Want AuthnRequests Signed</literal>
                        </entry>
                        <entry>
                            Allows you to specify whether the brokered identity provider is expecting signed SAML authentication requests or not.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <literal>Force Authentication</literal>
                        </entry>
                        <entry>
                            Allows you to tell the brokered identity provider that user must be authenticated even if he was previously authenticated (re-authentication) in the same session.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <literal>Validate Signature</literal>
                        </entry>
                        <entry>
                            Enable or disable signature validation of any message returned by the brokered identity provider.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <literal>HTTP-POST Binding Response</literal>
                        </entry>
                        <entry>
                            Allows you to specify if responses from the brokered identity providers are returned using the HTTP-POST or HTTP-Redirect protocol bindings. If enabled, only responses using HTTP-POST binding are accepted.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <literal>HTTP-POST Binding for AuthnReques</literal>
                        </entry>
                        <entry>
                            Allows you to specify wheter SAML authentication requests must be sent using the HTTP-POST or HTTP-Redirect protocol bindings. If enabled, it will send requests using HTTP-POST binding.
                        </entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
        <para>
            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.
        </para>
        <para>
            Once you create a SAML provider, there is an <literal>EXPORT</literal> button that appears when viewing that provider.
            Clicking this button will export a SAML entity descriptor which you can use to
        </para>
    </section>

    <section>
        <title>OpenID Connect v1.0 Identity Providers</title>
        <para>
            Keycloak can broker identity providers based on the OpenID Connect v1.0 protocol.
        </para>
        <para>
            In order to configure a OIDC identity provider, follow these steps:
        </para>
        <orderedlist>
            <listitem>
                <para>
                    Select the <literal>OpenID Connect v1.0</literal> identity provider from the drop-down box on the top right corner of the identity providers table in Keycloak's Admin Console. You should be presented with a specific page to configure the selected provider.
                </para>
            </listitem>
        </orderedlist>
        <para>
            When configuring an OIDC identity provider you are presented with different configuration options in order to send authentication requests to the external identity provider. In this case, the brokered identity provider must support the Authorization Code Flow (as defined by the specification) in order to authenticate the user and authorize access for the scopes specified in the configuration.
        </para>
        <table>
            <title>Configuration Options</title>
            <tgroup align="left" cols="2">
                <thead>
                    <row>
                        <entry>
                            Configuration
                        </entry>
                        <entry>
                            Description
                        </entry>
                    </row>
                </thead>
                <tbody valign="top">
                    <row>
                        <entry>
                            <literal>Authorization Url</literal>
                        </entry>
                        <entry>
                            The authorization url.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <literal>Token Url</literal>
                        </entry>
                        <entry>
                            The token url.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <literal>Logout Url</literal>
                        </entry>
                        <entry>
                            The IDP logout url.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <literal>Backchannel Logout</literal>
                        </entry>
                        <entry>
                            If set to true, logout to the external IDP will be done in a background HTTP request.  If
                            set to false, then the browser will be redirected to the external IDP to perform the logout.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <literal>User Info Url</literal>
                        </entry>
                        <entry>
                            The user info url. This is usually an url from where Keycloak will obtain user information in order to create a local account.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <literal>Client ID</literal>
                        </entry>
                        <entry>
                            The client id is usually generated when configuring an application or a project on the brokered identity provider.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <literal>Client Secret</literal>
                        </entry>
                        <entry>
                            The client secret is usually generated when configuring an application or a project on the brokered identity provider.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <literal>Issuer</literal>
                        </entry>
                        <entry>
                            Allows you to specify the expected value for the "issuer" claim when validating the ID token.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <literal>Default Scopes</literal>
                        </entry>
                        <entry>
                            Allows you to specify additional scopes when asking for user authentication and consent. By default, scope <literal>openid</literal> is always appended to the list of the scopes.
                        </entry>
                    </row>
                    <row>
                        <entry>
                            <literal>Prompt</literal>
                        </entry>
                        <entry>
                            Allows you to specify how the brokered identity provider must prompt user for authentication. You must check which values are supported by the brokered identity provider before choosing a value.
                        </entry>
                    </row>
                </tbody>
            </tgroup>
        </table>
        <para>
            You can also import all this configuration data by providing a URL or file that points to OpenID Provider Metadata (see OIDC Discovery specification)
        </para>
    </section>

    <section>
        <title>Retrieving Tokens from Identity Providers</title>
        <para>
            Keycloak allows you to store tokens and responses from identity providers during the authentication process.
            For that, you can use the <literal>Store Token</literal> configuration option, as mentioned before.
        </para>
        <para>
            It also allows you to retrieve these tokens and responses once the user is authenticated in order to use their
            information or use them to invoke external resources protected by these tokens.
            The latter case is usually related with social providers,
            where you usually need to use their tokens to invoke methods on their APIs.
        </para>
        <para>
            To retrieve a token for a particular identity provider you need to send a request as follows:
        </para>
        <programlisting language="JAVA"><![CDATA[GET /auth/realms/{realm}/broker/{provider_alias}/token HTTP/1.1
Host: localhost:8080
Authorization: Bearer {keycloak_access_token}]]></programlisting>
        <para>
            In this case, given that you are accessing an protected service in Keycloak, you need to send the access token
            issued by Keycloak during the user authentication.
        </para>
        <para>
            By default, the Keycloak access token issued for the application can't be automatically used for retrieve thirdparty token.
            A user will have to have the <literal>broker.read-token</literal> role.  The client will also have to have that role
            in its scope.  In the broker configuration page you can automatically assign this role to newly imported users by
            turning on the <literal>Stored Tokens Readable</literal> switch.
        </para>
        <note>
            <para>
                If your application is not at the same origin as the authentication server, make sure you have properly configured CORS.
            </para>
        </note>
    </section>

    <section>
        <title>Automatically Select and Identity Provider</title>
        <para>
            Applications can automatically select an identity provider in order to authenticate an user. In this case, the user will not be presented to the login page but automatically redirected to the identity provider.
        </para>
        <para>
            Keycloak supports a specific HTTP query parameter that you can use as a hint to tell the server which identity provider should be used to authenticate the user.
        </para>
        <para>
            For that, you can append the <literal>kc_idp_hint</literal> as a query parameter to your application url, as follows:
        </para>
        <programlisting language="JAVA"><![CDATA[GET /myapplication.com?kc_idp_hint=facebook HTTP/1.1
Host: localhost:8080]]></programlisting>
        <para>
            In this case, is expected that your realm has an identity provider with an alias <literal>facebook</literal>.
        </para>
        <para>
            If you are using <literal>keycloak.js</literal> adapter, you can also achieve the same behavior:
        </para>
        <programlisting language="JAVA"><![CDATA[var keycloak = new Keycloak('keycloak.json');

keycloak.createLoginUrl({
	idpHint: 'facebook'
});]]></programlisting>
    </section>

    <section>
        <title>Mapping/Importing SAML and OIDC Metadata</title>
        <para>
            You can import SAML assertion data, OpenID Connect ID Token claims, and Keycloak access token claims
            into new users that are imported from a brokered IDP.  After you configure a broker, you'll see a <literal>Mappers</literal>
            button appear.  Click on that and you'll get to the list of mappers that are assigned to this broker.  There is a
            <literal>Create</literal> 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.  You can assign
            a role mapping to a user if a claim or external role exists.  There's a bunch of options here so just mouse over
            the tool tips to see what each mapper can do for you.
        </para>
    </section>

    <section>
        <title>Examples</title>
        <para>
            Keycloak provides some useful examples about how to use it as an identity broker.
            Take a look at <literal>{KEYCLOAK_HOME}/examples/broker</literal> for more details.
        </para>
        <para>
            Each example application has its own README file where you can find additional information about how to configure Keycloak and
            run it.
        </para>
    </section>
</chapter>