# Keycloak Broker: Brokering a Keycloak SAML v2 Identity Provider Quickstart

What is it?
-----------

This example demonstrates how to broker a SAML Identity Provider in Keycloak. In this case, the SAML Identity Provider
belongs to a different realm than the application and we want to trust users from one realm to authenticate and access the
applications in another realm.

There are two main realms in this example:

* **saml-broker-realm.json**: the realm where the user belongs and that provides a SAML v2 Identity Provider.
* **saml-broker-authentication-realm.json**: the realm with all the necessary configuration to setup the application and the
identity provider responsible for brokering.

From this example you'll understand how to setup an identity provider in order to broker an external
SAML identity provider and allow users from different domains/realms to authenticate and access applications in a realm.

The *saml-broker-realm* realm provides two important configuration. The first one is the user that we are going to use to
authenticate with the SAML Identity Provider.

    {
        "username" : "user",
        "enabled": true,
        "email" : "user@saml-broker-realm",
        "firstName": "User",
        "lastName": "SAML",
        "credentials" : [
            { "type" : "password",
                "value" : "password" }
        ]
    }

The second one is an application to configure a SAML Identity Provider to authenticate requests from the other realm.

    {
        "name": "http://localhost:8080/auth/",
        "enabled": true,
        "redirectUris": [
          "http://localhost:8080/auth/broker/saml-broker-authentication-realm/saml-identity-provider"
        ],
      "attributes": {
        "saml.assertion.signature": "true",
        "saml.server.signature": "true",
        "saml.signature.algorithm": "RSA_SHA256",
        "saml.client.signature": "true",
        "saml.authnstatement": "true",
        "saml.signing.private.key": " ",
        "saml.signing.certificate": " "
      }
    }

The *saml-broker-authentication-realm.json* realm provides the configuration for the application and also the necessary
configuration to setup an identity provider to broker the SAML Identity Provider from the other realm.

    {
      "id" : "saml-identity-provider",
      "providerId" : "saml",
      "name" : "SAML v2 Identity Provider",
      "enabled": true,
      "updateProfileFirstLogin" : "true",
      "storeToken" : "true",
      "addReadTokenRoleOnCreate": true,
      "config": {
          "singleSignOnServiceUrl": "http://localhost:8080/auth/realms/saml-broker-realm/protocol/saml",
          "singleLogoutServiceUrl": "http://localhost:8080/auth/realms/saml-broker-realm/protocol/saml",
          "nameIDPolicyFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
          "signingCertificate": " ",
          "wantAuthnRequestsSigned": true,
          "forceAuthn": true,
          "validateSignature": true,
          "postBindingResponse": true,
          "postBindingAuthnRequest": true
      }
    }

Basically, once you try to access the application for the first time, you'll be redirected to *saml-broker-authentication-realm*'s login page.
In this page you'll note that there is a "SAML v2 Identity Provider" button that allows you to authenticate with the SAML Identity Provider
in *saml-broker-realm* realm.

After clicking that button, you'll be redirected to *saml-broker-realm*'s login page from where you must authenticate using the
credentials for the default user:

    Username: user
    Password: password

If everything is fine, the *saml-broker-realm* realm will redirect you back to *saml-broker-authentication-realm* and at
this point you'll be asked to provide some basic profile information in order to create a new user in *saml-broker-authentication-realm* based
on the information returned by the SAML Identity Provider.
Once you update your profile, you'll be authenticated and redirected to the application.

At the end, the *user* user is now federated and can access the application in *saml-broker-authentication-realm* realm.

Import the necessary realms
--------------------------------------
Next thing you have to do is import the test realm for the demo.  Clicking on the below link will bring you to the
create realm page in the Admin UI.  The username/password is admin/admin to login in.  Keycloak will ask you to
create a new admin password before you can go to the create realm page.

[http://localhost:8080/auth/admin/master/console/#/create/realm](http://localhost:8080/auth/admin/master/console/#/create/realm)

Import the following realms:

* **saml-broker-authentication-realm.json**
* **saml-broker-realm.json**

Make sure you've set up the Keycloak Server
--------------------------------------
The Keycloak Appliance Distribution comes with a preconfigured Keycloak server (based on Wildfly).  You can use it out of
the box to run these demos.  So, if you're using this, you can head to Step 2.

Alternatively, you can install the Keycloak Server onto any EAP 6.x, or Wildfly 8.x server, but there is
a few steps you must follow.

Obtain latest keycloak-war-dist-all.zip.  This distro is used to install Keycloak onto an existing JBoss installation.
This installs the server.

    $ cd ${wildfly.jboss.home}/standalone
    $ cp -r ${keycloak-war-dist-all}/deployments .

To be able to run the demos you also need to install the Keycloak client adapter. For Wildfly:

    $ cd ${wildfly.home}
    $ unzip ${keycloak-war-dist-all}/adapters/keycloak-wildfly-adapter-dist.zip

For JBoss EAP 6.x

    $ cd ${eap.home}
    $ unzip ${keycloak-war-dist-all}/adapters/keycloak-eap6-adapter-dist.zip

For JBoss AS 7.1.1:

    $ cd ${as7.home}
    $ unzip ${keycloak-war-dist-all}/adapters/keycloak-as7-adapter-dist.zip

Unzipping the adapter ZIP only installs the JAR files.  You must also add the Keycloak Subsystem to the server's
configuration (standalone/configuration/standalone.xml).

    <server xmlns="urn:jboss:domain:1.4">

        <extensions>
            <extension module="org.keycloak.keycloak-subsystem"/>
            ...
        </extensions>

        <profile>
            <subsystem xmlns="urn:jboss:domain:keycloak:1.0"/>
            ...
        </profile>

Boot Keycloak Server
---------------------------------------
Where you go to start up the Keycloak Server depends on which distro you installed.

From appliance:

```
$ cd keycloak/bin
$ ./standalone.sh
```


From existing Wildfly/EAP6/AS7 distro

```
$ cd ${wildfly.jboss.home}/bin
$ ./standalone.sh
```


Start JBoss Enterprise Application Platform 6 or WildFly with the Web Profile
-------------------------

1. Open a command line and navigate to the root of the JBoss server directory.
2. The following shows the command line to start the server with the web profile:

        For Linux:   JBOSS_HOME/bin/standalone.sh
        For Windows: JBOSS_HOME\bin\standalone.bat


Build and Deploy the Quickstart
-------------------------

_NOTE: The following build command assumes you have configured your Maven user settings. If you have not, you must include Maven setting arguments on the command line. See [Build and Deploy the Quickstarts](../README.md#build-and-deploy-the-quickstarts) for complete instructions and additional options._

1. Make sure you have started the JBoss Server as described above.
2. Open a command line and navigate to the root directory of this quickstart.
3. Type this command to build and deploy the archive:

        For EAP 6:     mvn clean package jboss-as:deploy
        For WildFly:   mvn -Pwildfly clean package wildfly:deploy

4. This will deploy `target/saml-broker-authentication.war` to the running instance of the server.


Access the application
---------------------

The application will be running at the following URL: <http://localhost:8080/saml-broker-authentication>.


Undeploy the Archive
--------------------

1. Make sure you have started the JBoss Server as described above.
2. Open a command line and navigate to the root directory of this quickstart.
3. When you are finished testing, type this command to undeploy the archive:

        For EAP 6:     mvn jboss-as:undeploy
        For WildFly:   mvn -Pwildfly wildfly:undeploy


Debug the Application
------------------------------------

If you want to debug the source code or look at the Javadocs of any library in the project, run either of the following commands to pull them into your local repository. The IDE should then detect them.

        mvn dependency:sources
        mvn dependency:resolve -Dclassifier=javadoc