Uitid/pk 41 keycloak switch #408

erwin1 · 2024-10-17T08:43:41Z

Changed

Removed Auth0 references from documentation
Updated documentation to Keycloak

Ticket: https://jira.uitdatabank.be/browse/PK-41

…tion

grubolsch · 2024-11-04T08:12:26Z

projects/authentication/docs/client-access-token.md

@@ -81,7 +83,7 @@ Authorization: Bearer YOUR_ACCESS_TOKEN

 #### More info

-publiq currently uses [Auth0](https://auth0.com/) as the implementation of its authentication and authorization service. For more in-depth information about requesting client access tokens, see the [Auth0 documentation for the client\_credentials flow](https://auth0.com/docs/flows#client-credentials-flow).
+publiq currently uses [Keycloak](https://www.keycloak.org/) as the implementation of its authentication and authorization service. For more in-depth information about requesting client access tokens, see the [OAuth 2.0 specification for the client\_credentials flow](https://datatracker.ietf.org/doc/html/rfc6749#section-4.4).


Is there any reason why we should communicate that we are using keycloak?
All urls/flows are just oauth compatible, and we do not link to any specific keycloak docs, so I would not give this information away.
This could be valuable info for a hacker with bad intensions.

the reason is simple: Auth0 was mentioned and I changed Auth0 to Keycloak. It's a fair point we don't have to mention it. I'll rephrase.

OTOH it's not a secret (and shouldn't be) that we are using Keycloak. It's obvious in many other ways.

Update: we also have this line: https://github.com/cultuurnet/apidocs/pull/408/files#diff-09205b70e866174fcdc81ff1f865f6208b9149eca7d675d3b0bf4589886034b6R15

So if we don't want to talk about keycloak we have to remove that line as well.

projects/authentication/docs/user-access-token.md

grubolsch · 2024-11-04T08:23:20Z

projects/authentication/docs/user-access-token.md

@@ -15,7 +28,7 @@ See [requesting client credentials](./requesting-credentials.md) how to obtain a

 Additionally, we will need to configure the following settings for your client on our end:

-* **Login URL**: In some cases the authorization server will need to redirect the user back to a login URL on your application. This URL should point to a route in your application that ends up redirecting to the `/authorize` endpoint on publiq's authorization server, e.g. `https://example.com/login`. Note that it requires `https` and it cannot point to `localhost`. It can include query parameters and a URI fragment.
+* **Login URL**: In some cases the authorization server will need to redirect the user back to a login URL on your application. This URL should point to a route in your application that ends up redirecting to the `/realms/uitid/protocol/openid-connect/auth` endpoint on publiq's authorization server, e.g. `https://example.com/login`. Note that it requires `https` and it cannot point to `localhost`. It can include query parameters and a URI fragment.
 * **Callback URL(s)**: The absolute URL(s) of the page(s) where your users can be redirected back to after they log in. You can specify any callback URL whenever you redirect a user to the authorization server to log in, but it needs to be registered on our end first to prevent phishing attacks. For example `https://example.com/authorize` for your production application, and/or `https://localhost:8080/authorize` for local development.
 * **Logout URL(s)**: The absolute URL(s) of the page(s) where you users can be redirected back to after they log out. You can specify any logout URL whenever you redirect a user to the authorization server to log out, but it needs to be registered on our end first to prevent phishing attacks. For example `https://example.com` if you want to redirect the user back to the homepage of your application after logging out, or `https://example.com/logged-out` if you want to redirect them to a page with a confirmation message like "You're logged out!" after logging out. Like callback URL(s), logout URL(s) may use `https://localhost` for local development.


Maybe add a line that it is end-slash sensitive ?
Common error.

grubolsch · 2024-11-04T08:24:01Z

projects/authentication/docs/user-access-token.md

    Auth server-->>User: Show login page
    User-->>Auth server: Login and give consent
    Auth server-->>Client: Redirect back to callback URL with authorization code
-    Client->>Auth server: POST /oauth/token with authorization code<br /> and client credentials
+    Client->>Auth server: POST /token with authorization code<br /> and client credentials


Suggested change

Client->>Auth server: POST /token with authorization code<br /> and client credentials

Client->>Auth server: POST /realms/uitid/protocol/openid-connect/token with authorization code<br /> and client credentials

This is the mermaid diagram and I explicitly chose to leave out the full path. Maybe I can reduce confusion further by getting rid of the /

This is how it looks like with the full path:

Changed to full path

projects/authentication/docs/client-access-token.md

grubolsch · 2024-11-04T08:37:01Z

projects/authentication/docs/user-access-token.md


 <!-- theme: success -->

 > ##### SDK
 >
-> If you want, you can use the [Regular Web Application SDK Libraries](https://auth0.com/docs/libraries#webapp) provided by Auth0 to implement this flow.
+> It is a good practice to use an OpenID Connect compliant client SDK. SDKs exist in different languages and flavors, so the best choice greatly depends on your specific application. The OpenID.net website contains a list of [certicied](https://openid.net/developers/certified-openid-connect-implementations/) and [uncertified](https://openid.net/developers/uncertified-openid-connect-implementations/) SDKs. To configure your SDK you might need this configuration: `https://account-test.uitid.be/.well-known/openid-configuration`.


Same remark regarding mentioning Keycloak.

grubolsch · 2024-11-04T08:37:37Z

projects/authentication/docs/user-access-token.md

@@ -159,11 +162,11 @@ sequenceDiagram
    actor User
    User-->>Client: Click login link
    Client->>Client: Generate code_verifier and code_challenge
-    Client->>Auth server: Redirect to GET /authorize with code_challenge
+    Client->>Auth server: Redirect to GET /auth with code_challenge


Suggested change

Client->>Auth server: Redirect to GET /auth with code_challenge

Client->>Auth server: Redirect to GET /realms/uitid/protocol/openid-connect/auth with code_challenge

grubolsch · 2024-11-04T08:37:49Z

projects/authentication/docs/user-access-token.md

    Auth server-->>User: Show login page
    User-->>Auth server: Login and give consent
    Auth server-->>Client: Redirect back to callback URL with authorization code
-    Client->>Auth server: POST /oauth/token with authorization code,<br /> client id and code_verifier
+    Client->>Auth server: POST /token with authorization code,<br /> client id and code_verifier


Suggested change

Client->>Auth server: POST /token with authorization code,<br /> client id and code_verifier

Client->>Auth server: POST /realms/uitid/protocol/openid-connect/token with authorization code,<br /> client id and code_verifier

projects/authentication/docs/user-access-token.md

grubolsch · 2024-11-04T08:40:44Z

projects/authentication/docs/user-access-token.md

@@ -430,9 +419,9 @@ The best way to check if a refresh token is expired is to exchange it for an acc

 When the user of your application wants to log out, clear any session data in your application including the user's access token and refresh token. If you have cached the [user's info](#user-info), make sure to also clear that.

-Afterward, you should **redirect** the user to the `/logout` URL on the authorization server so the user's session is also cleared there. This redirect will be invisible to the end user, as the authorization server will simply clear the user's session and then redirect back to your application based on a `?returnTo=...` URL parameter that you can specify. Note that you can only use an allowed "logout URL" as value for the `returnTo` URL parameter. (See [Requirements](#requirements))
+Afterward, you should **redirect** the user to the `/realms/uitid/protocol/openid-connect/logout` URL on the authorization server so the user's session is also cleared there. This redirect will be invisible to the end user, as the authorization server will simply clear the user's session and then redirect back to your application based on a `?post_logout_redirect_uris=...` URL parameter that you can specify. Note that you can only use an allowed "logout URL" as value for the `post_logout_redirect_uris` URL parameter. (See [Requirements](#requirements))



Maybe also add a paragraph about id_token_hint ?

Fair point. It's mentioned in the link behind the link behind OpenID Connect RP-Initiated Logout in the following paragraph, but I can make it more explicit.

Co-authored-by: Koen Eelen <[email protected]>

…pidocs into uitid/PK-41-keycloak-switch

erwin1 added 6 commits October 15, 2024 13:55

PK-41 replace Auth0 with Keycloak in client credential flow documenta…

40608e2

…tion

PK-41 fix try it out section

142a475

PK-41 replace try it with curl sample

44c4e0a

PK-41 backward compatiblity

c0e3e48

PK-41 update user access token documentation to keycloak

34b08a2

fix ui_locales

69339a5

erwin1 requested a review from hanshenderickx October 17, 2024 08:43

erwin1 requested review from corneelwille, JurgenG and JonasVHG as code owners October 17, 2024 08:43

fix linting

bcb9b3e

grubolsch requested changes Nov 4, 2024

View reviewed changes

erwin1 and others added 5 commits November 6, 2024 14:52

PR remarks

14349a2

PR remarks

e19764b

Update projects/authentication/docs/client-access-token.md

ee04911

Co-authored-by: Koen Eelen <[email protected]>

PR remarks

62d19d9

Merge branch 'uitid/PK-41-keycloak-switch' of github.com:cultuurnet/a…

c1ea3a0

…pidocs into uitid/PK-41-keycloak-switch

erwin1 requested a review from grubolsch November 7, 2024 09:34

grubolsch approved these changes Nov 7, 2024

View reviewed changes

erwin1 merged commit 0e37ffc into main Nov 7, 2024
10 checks passed

erwin1 deleted the uitid/PK-41-keycloak-switch branch November 7, 2024 10:06

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uitid/pk 41 keycloak switch #408

Uitid/pk 41 keycloak switch #408

erwin1 commented Oct 17, 2024

grubolsch Nov 4, 2024

erwin1 Nov 6, 2024

erwin1 Nov 7, 2024

grubolsch Nov 4, 2024

erwin1 Nov 7, 2024

grubolsch Nov 4, 2024

erwin1 Nov 6, 2024

erwin1 Nov 7, 2024

grubolsch Nov 4, 2024

grubolsch Nov 4, 2024

grubolsch Nov 4, 2024

grubolsch Nov 4, 2024

erwin1 Nov 6, 2024

erwin1 Nov 7, 2024

	Client->>Auth server: POST /token with authorization code<br /> and client credentials
	Client->>Auth server: POST /realms/uitid/protocol/openid-connect/token with authorization code<br /> and client credentials

	Client->>Auth server: Redirect to GET /auth with code_challenge
	Client->>Auth server: Redirect to GET /realms/uitid/protocol/openid-connect/auth with code_challenge

Uitid/pk 41 keycloak switch #408

Uitid/pk 41 keycloak switch #408

Conversation

erwin1 commented Oct 17, 2024

Changed

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment