Add section about setting up OIDC as external authentication provider #1301
Conversation
|
@CSDUMMI is attempting to deploy a commit to the Mastodon Team on Vercel. A member of the Team first needs to authorize it. |
CSDUMMI
changed the title
| OIDC_RESPONSE_TYPE= | ||
| OIDC_RESPONSE_MODE= | ||
| OIDC_DISPLAY= | ||
| OIDC_PROMPT= |
There was a problem hiding this comment.
In mastodon/mastodon#31131 I'm adding support for PKCE with OIDC providers, so if that's merged before this documentation change lands, we should make sure that it is documented here too.
OIDC_USE_PKCE which is "true" to enable, all other values result in PKCE being disabled.
| ``` | ||
| OIDC_ENABLED=true | ||
| OIDC_ISSUER=<URI to IdP> # For Keycloak, this is the realm's URI. | ||
| OIDC_DISCOVERY=true |
There was a problem hiding this comment.
Just a heads up, this can't be used in development with a HTTP scheme issuer, as it crashes because something deep inside omniauth_openid_connect forces HTTPS scheme.
So for a HTTP scheme OIDC provider, you need to provide the _ENDPOINTs manually, along with the issuer:
OIDC_ISSUER=http://localhost:9000/
OIDC_AUTH_ENDPOINT=http://localhost:9000/application/o/authorize/
OIDC_TOKEN_ENDPOINT=http://localhost:9000/application/o/token/
OIDC_USER_INFO_ENDPOINT=http://localhost:9000/application/o/userinfo/
OIDC_JWKS_URI=http://localhost:9000/application/o/mastodon/jwks/
OIDC_END_SESSION_ENDPOINT=http://localhost:9000/application/o/mastodon/end-session/
OIDC_END_SESSION_ENDPOINT allows for doing proper "logout" where you can actually logout of the issuer as well; I'd highly recommend folks setting this, otherwise users are never fully logged out (just the mastodon session is destroyed, the session at the OIDC provider is not destroyed)
| OIDC_REDIRECT_URI=https://<Mastodon Domain>/auth/auth/openid_connect/callback | ||
| OIDC_SECURITY_ASSUME_EMAIL_IS_VERIFIED=true | ||
| OIDC_CLIENT_SECRET= # create a confidential client secret with your IdP and provide it here. | ||
| OIDC_SCOPE=openid,profile,email # Keycloak specific, maybe adjusted to your identity provider. |
There was a problem hiding this comment.
| OIDC_SCOPE=openid,profile,email # Keycloak specific, maybe adjusted to your identity provider. | |
| OIDC_SCOPE=openid,profile,email |
These are standard OIDC scopes, and pretty much every OIDC server should have them.
| OIDC_CLIENT_ID=mastodon # the client id configured with the IdP.In OIDC, the client is Mastodon. | ||
| OIDC_REDIRECT_URI=https://<Mastodon Domain>/auth/auth/openid_connect/callback | ||
| OIDC_SECURITY_ASSUME_EMAIL_IS_VERIFIED=true | ||
| OIDC_CLIENT_SECRET= # create a confidential client secret with your IdP and provide it here. |
There was a problem hiding this comment.
| OIDC_CLIENT_ID=mastodon # the client id configured with the IdP.In OIDC, the client is Mastodon. | |
| OIDC_REDIRECT_URI=https://<Mastodon Domain>/auth/auth/openid_connect/callback | |
| OIDC_SECURITY_ASSUME_EMAIL_IS_VERIFIED=true | |
| OIDC_CLIENT_SECRET= # create a confidential client secret with your IdP and provide it here. | |
| OIDC_CLIENT_ID=mastodon # the client id configured with the IdP.In OIDC, the client is Mastodon. | |
| OIDC_CLIENT_SECRET= # create a confidential client secret with your IdP and provide it here. | |
| OIDC_REDIRECT_URI=https://<Mastodon Domain>/auth/auth/openid_connect/callback | |
| OIDC_SECURITY_ASSUME_EMAIL_IS_VERIFIED=true |
Keep client credentials together
| OIDC_PROMPT= | ||
| OIDC_SEND_NONCE= | ||
| OIDC_SEND_SCOPE_TO_TOKEN_ENDPOINT= | ||
| OIDC_IDP_LOGOUT_REDIRECT_URI= |
There was a problem hiding this comment.
This can be used in combination with OIDC_END_SESSION_ENDPOINT to redirect the user back to Mastodon after they have signed out.
| # OmniAuth | ||
| Mastodon supports the CAS, SAML and OpenID Connect protocols for external authentication. | ||
| These can either be configured in addition to native logins on Mastodon or as the sole | ||
| identity provider using `OMNIAUTH_ONLY=true`. |
There was a problem hiding this comment.
Also needs docs for ONE_CLICK_SSO_LOGIN currently this is hiding under CAS at the bottom of the page, when these two options are usually used together.
And there's SSO_ACCOUNT_SETTINGS and SSO_ACCOUNT_SIGN_UP
The current section on Single-Sign On in the mastodon documentation is marked as under construction.
This PR adds a section about setting up OIDC as a SSO method. The documentation is based on my own setup, using keycloak as an IdP, but should be general enough to apply to other IdPs as well.
Sections on SAML and CAS are added, but left empty, as I have no running setup with either of these SSO methods.