Add some correction in the Auth tutorial for Keycloak

[Haydgoki]

Hello !

The doc was not working to add a keycloak SSO integration, So we correct it and we want to update it !

Best regards.

[LeoColomb]

It is really good to mention.
That said, I believe it would be more future-proof and more robust to simply provide the link to the relevant documentation.

Suggested change

	Finally on the keycloak side, you'll have to add the audiance mapper.
	To do so :
	1. Go on your Keycloak admin board
	2. Go on your client
	3. On the Mappers tab, click create
	4. * Name : "aud"
	* Type : Audiance
	* Included Custom Audience : \<Your Client Name\>
	5. Click save
	A hardcoded custom audience mapper is often required on Keycloak.
	Please refer to the [Keycloak's official documentation](https://www.keycloak.org/docs/latest/server_admin/#_audience_hardcoded).

[Haydgoki]

I agree with that. But the documentation does not speciy that we need a custom audiance. I prefer to keep and simplify the explaination and still precise that we need a custom audiance, and beside it add the documentation !

[LeoColomb]

Thanks for your reply, @Haydgoki.
I'm not sure to understand it, though. In my suggestion change, the custom audience need is still mentioned, but with a link to the Keycloak documentation on how to make it concrete.
Isn't that sufficient?

[Haydgoki]

Hey !
In fact it is suffisant when you already know the tool.

• But imo i would prefer more precision for the fact that you'll have to enter a value in the "custom audiance" field. Because the confusion with the "client audiance field" could exists.
• Plus we need to precise that it has to be set to the value with the client name in it.
• And I don't remember about my tests, but the fact that the audiance is name "aud" is important !

And for those reasons, I think we could keep the two commits about this point !

[LeoColomb]

• enter a value in the "custom audiance" field. Because the confusion with the "client audiance field" could exists.
• the audiance is name "aud" is important

I can't find any reference to these, either in the official documentations or the implementations.

• https://python-social-auth.readthedocs.io/en/latest/backends/keycloak.html
• https://github.com/python-social-auth/social-core/blob/d9554fa40e751c85ae60231fe2f5bd5a528c4452/social_core/backends/keycloak.py#L7-L96
• https://www.keycloak.org/docs/latest/server_admin/#_audience_hardcoded

Do you have any reference?

[Haydgoki]

Nop, just my tests. That was the problem, the lack of reference for these problems. I had to experiment a lot to make it work.

The thing is when we specified a value for the audience in the "Included value audience" it returns you an error :
MissingRequiredClaimError at /oauth/complete/keycloak/ : Token is missing the "aud" claim
When you check the local vars on the debug section (on the netbox page), you get an audience var and the Payload var (JWT token). The audience has to be in the token, not in an independant var. So when you enter the client ID has a value in the mappers on the "Included Custom Audience" instead of the "Included Client Audience", it works.

Now for the Mapper name of the audience, I retest that part, and you can name it whatever you want