Identity federation – More than connecting to Facebook?

When you need to work with your client's users you always think about how you can convince him to get access to his customer database? – There's a solution for you and your customer, who does not need to share his whole database with you! Instead, you are just given the users that interact with your system and agree to share their information with your application.

There are various reasons nowadays for identity federation between providers, besides the often-used social login with Facebook (or any other social network). Imagine you’re building a system for a client which is being used by a limited but indefinable group of his customers. What are you going to do?

This question could be answered very easily: Ask your client to give you access to his customer database. On the other hand, would you open your customer database to a contractor?

Well, the next solution would be to just use the identity provider of your client. As you can imagine, this also has some drawbacks:

Every time you need to add a new client application, you need to ask your client.
If you need additional users, does your client allow them to be stored in his user management? (and do you want that?)
What are your plans if your client decides to move to a new protocol for authentication? Rewriting your whole application landscape? For sure that won’t be your answer. 😉
Probably you plan to offer this product to more clients than just this one.

Let’s summarize first:

You don’t want to rely on your client to get full access to all his users (because this won’t happen anyway)
You want to minimize the need to ask your client for service actions (adding new client applications etc.)
You don’t want to store your users (whether originated in your client or your application) in a foreign database
You want protocol stability.
You want extensibility when it comes to offering your product to more clients.

No problemo — Keycloak and OpenID Connect got you covered. By using identity federation, you can get access to information of users from client systems by leveraging the OpenID Connect functionality of id tokens and the userinfo endpoint.

How it works

Identity brokerage / identity federation process in Keycloak

– Source: Keycloak Documentation

The figure shows the process of identity federation (also called identity brokering in Keycloak’s terms) of a foreign ID Provider (short: IdP). The identity broker, highlighted with a green background, will be your Keycloak installation. Service provider will be your client application and the identity provider on the right will be replaced by your customer’s identity provider.

I’ll explain the process step-by-step:

A user sends a request to your client application.
Because he did not supply a valid access token (or any token at all), he’ll be redirected to your Keycloak.
Keycloak will present him a login mask and a selection of identity providers. (including the one of your client) [optional: By supplying the target IdP you can skip this and the next step]
The user selects the desired IdP
The user is redirected to the login of the IdP
The user is then asked for his login credentials. If he’s already logged in at the IdP, he could be asked if he consents to sharing credentials with your application. (=> Your Keycloak)
If he agreed he’ll be redirected to your Keycloak with an authorization code.
Your Keycloak will now exchange this authorization code (from step 7) for an access and id token, which contains information about the authenticated user. This information is then used to create a local copy of the user in the Keycloak user database. If more information is required, the userinfo endpoint is leveraged with the access token being supplied before.
An access and id token are presented to the application, that initiated the authentication flow. This access and id tokens are created by your Keycloak and as a result only valid for applications using your Keycloak as an authorization server.

Conclusion

By using identity federation, you have a lot of benefits, compared to the alternatives listed at the begin:

Only client’s users, who later use your system, are exchanged with you.
The client can limit information being exchanged with you. (e. g. he can decide not to share user’s SSN [= social security number] or credit card information with you, because he’s legally not allowed to)
- If you need this information, ask the user for it in your application and attach it to his account that’s being held in your database.
You can decide what information to store. (The minimum information to store is an user id or an username to link between your data and the one of the IdP)
You can leverage identity federation even more by adding multiple identity providers. As long as they support OpenID Connect or SAML (another authentication protocol) and they allow you to add a client into their identity provider, you can simply configure a new identity provider in your Keycloak. No code required at all.
You can add additional users to your system without sharing them with your client. E. g. service technician accounts.
You’re responsible for client (application) management. No need to rely on the service desk of your client.
- This means your application landscape is free to grow in size

But there are a few things you should think about:

The users stored in your system are copies with state of the last successful login
- If the user is deleted in the source system meanwhile, he’s still in your system
Don’t let federated users set a password unless you don’t care if they are in the worst case never synchronized with the source system again
- If a user sets a password and his account is deleted in the source system later on. He can directly login to your system using the credentials he entered when changing his password on your system. There’s no way for your system to find out about his state on the source system.
- My tip: Don’t use the account management system supplied by Keycloak by default if you could consider the problem listed above.
Decide on a constant, never changing and never re-assigned user identifier like his user id.
- e.g. if you use his username, which could be changed, you can have duplicate accounts in your database. You won’t be informed about username changes by the federated system.
- e.g. if somebody deletes his account and his user id is assigned to a new user, the new user will be able to see data entered by the old user in your system.
- Both examples will lead into major privacy problems if not handled with care!
You are now an identity provider as well. Besides all advantages you’re responsible for every bit of data that’s shared with you.