SSO — Multiple Identity Providers with Keycloak — Tutorial
Have you ever wondered about how to allow users to login with their google user accounts in your system? And accounts from other Auth Servers?
Some of our customers have these questions:
Where are my user details stored? Do I have to register into your system and fulfill a form? How do you secure my personal details?
At my current employer, we gather requirements from other departments based on comments like:
I have my users’ data stored in a database, and I want to use/integrate your services but I don’t want you to manage that data.
Or…
We have our own Auth Server. Our users don’t want to create another account. How can we do SSO to your system?
In this article you will find the step-by-step (with screenshots) tutorial of how to setup a local environment so that you can start discovering yourself how to configure an Auth Server like Keycloak to perform SSO and use accounts from different providers.
The intention is to show that you can have an Auth Server but no need to own/manage/maintain the Identity of your users.
What you will not find in this article is a deep explanation about SSO and the two protocols ( OIDC — OpenId Connect and SALM) offered by the Auth Server ( Keycloak)
The Internet is full of content explaining OIDC. I can give two of my preferences:
- OAuth and OpenID Connect for Microservices IMO, one of the best presentations to get you into OIDC
- OAuth in one picture
Prerequisites
Let’s get started!
You are going to have that design in your local.
You will be able to access to the protected service, using your credentials from your own google account
or the credentials from the External Auth Server
The core concept in Keycloak is a Realm. A realm secures and manages security metadata for a set of users, applications, and registered oauth clients.
The supplied resources are already ready to be loaded with the Realms, Clients and Identity Providers. However, the one for google, you will have to configure it with your own details.
Note: To start form scratch, you just need to comment out the lines where realms are being imported in the
docker-compose.yaml
.
Local environment
- Clone the github repository and go to the given folder
git clone git@github.com:antonioberben/examples.git
cd example/keycloak-multiple-id-providers
2. Start containers
docker-compose up -d
Hint: To see the last 10 lines of logs and keep watching the traces:
docker-compose --tail 10 -f
3. Get the your docker containers gateway IP
Depending on your host OS, docker creates a network and assigns an Gateway IP to route traffic to your host.
Figure out the containers name/ID:
docker-compose ps
Now figure out the gateway IP:
docker inspect <here container name/id> | grep Gateway
4. Adjust for domain resolution
Since you are in local, you need to simulate two different hostnames. One for My Auth Server
and the other one for External Auth Server
As you can see in docker-compose.yaml
file, docker will inject in /etc/hosts
file for each container, the specifications to route the traffic outside the container. You will work with my.auth.com
and external.auth.com
In docker-compose.yaml
:
[...]
extra_hosts:
my.auth.com: <here the gateway IP>
external.auth.com: <here the gateway IP>
[...]
Now you will have to add into your own local /etc/hosts
file the traces, but redirecting to localhost
/ 127.0.0.1
Why?
The reason is that the example requires run OIDC flows which requires re-directions from one container to another as well as re-directions from Google to one of the containers. This setup is quite simple, although, if you are familiar with nip.io, it will be better for you. But I did not want to add more complexity.
In your /etc/hosts
:
# keycloak example
127.0.0.1 external.auth.com my.auth.com
5. Stop, remove and start containers again
docker-compose stop
docker-compose rm -f
docker-compose up -d
After a while, you will be able to access the two different Auth Servers
- My Auth Server: http://my.auth.com:8180/auth
- External Auth Server: http://external.auth.com:8280/auth
Setup External Auth Server as Identity Provider
Since you want SSO using credentials from different providers, you have to configure both sides.
- In
My Auth Server
you configure oneIdentity Provider
for Google and another one forExternal Auth Server
. - In
Google
you configure aclient
- In
External Auth Server
you configure another client.
This is the way, through OIDC (OpenID Connect), to let both sides know each other and enable SSO.
- Go to
External Auth Server
( http://external.auth.com:8280/auth), with credentials:
user: admin
password: admin
These credentials are set in docker-compose.yaml
2. Create a realm with name external-auth
3. Create a client
It is important to mark the client as confidential
Confidential clients are required to provide a client secret when they exchange the temporary codes for tokens
And the Valid redirect URIs
needs to point to the Identity Provider
you are going to set up in parallel, so keep this tab open.
4. Open in another tab My Auth Server
( http://my.auth.com:8180/auth), with credentials:
user: admin
password: admin
5. Create a realm with name my-auth
6. Setup an Identity Provider which connects to External Auth Server
Here you need several points to pay attention.
Redirect URI
is the attribute you needed from the previous step when you were creating the clientAuthorization URL
andToken URL
are attributes you can find the explanation belowClient ID
andClient Secret
are attributes you can find from previous step when you created the client in the other server
Where do I get
Authorization URL
andToken URL
?Go to the
External Auth Server
,external-auth
realm, click onRealm Settings
and where it says:Endpoints: OpenID Endpoint Configuration
, it is actually a link. Then, click it and a new tab will be open with theDiscovery Endpoint
.
- Discovery Endpoint: http://external.auth.com:8280/auth/realms/external-auth/.well-known/openid-configuration
7. Save the configurations from both servers.
Now you have configure External Auth Server
as a My Auth Server
's Identity Provider.
Setup Google as Identity Provider
To set up Google as Identity Provider, follow these steps:
- Go to Google Developers Console and
credentials
2. Select OAuth client ID
As you can see, in Authorized redirect URIs
you set the value that you will obtain while configuring the My Auth Server
side in parallel.
Find the client ID
and client secret
which you will use in the next step
3. In parallel to Google setup, go to My Auth Server
and create a new Identity Provider. But this time, use one of the options which are offered: Google
. Configure it as follows:
Login to “Account” Service with External Auth Server account
- Go to My Auth Server and list the users. You will see there are non.
2. Go to External Auth Server and create a user external-user
. After saving, assign a password: password
.
3. Try to access the Account
service which actually is part of keycloak itself ( http://my.auth.com:8180/auth/realms/my-auth/account). You will be redirected to the login page where the new Identity Providers are offered. Click on the External Auth Server
provider
You will be redirected to the External Auth Server
login page.
4. Use the credentials you created for External Auth Server
user: external-user
password: password
5. After authentication succeeds, you are back to the Account
service, logged in with external user credentials
6. Let’s check the list of users in My Auth Server
. You will see now the Identity Image. This means that a copy of the identity from External Auth Server
has been stored in My Auth Server
. This gives the capabilities to My Auth Server
to release access tokens (in a JWT shape) for users which are not actually under its domain.
Login to Account Service with a Google account
- Try to access the
Account
service which actually is part of keycloak itself ( http://my.auth.com:8180/auth/realms/my-auth/account). You will be redirected to the login page where the new Identity Providers are offered. Click on theGoogle
provider
You will be redirected to the Google
login page.
2. After authentication succeeds, you are back to the Account
service, logged in with gmail credentials
3. Like you did before, let’s check the list of users in My Auth Server
. You will see now the Identity Image created for the Google account.
To see the Identity Provider related to the Identity Image, you can see it at user details, where it says: Identity Provider Links
.
Last thoughts
Now, you have full control of the Identity’s Images, but not of the identities themselves.
This means that you can release tokens, manage sessions, grant/revoke accesses to your own services, etc. But the Identity of the user stands in another system.
This removes the burden of maintaining the identities from your systems. Your users will not be required to go through a registration process in your system.
As well, it allows you to bring to your systems, users from different buckets (google, external auth server,…)
If you are interested in knowing more deep inside, you can ping me in twitter @antonio_berben
Originally published at https://antonioberben.gitlab.io on May 1, 2020.