Skip to content

Add section about setting up OIDC as external authentication provider #1301

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
CSDUMMI wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add section about setting up OIDC as external authentication provider #1301

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 62 additions & 0 deletions content/en/admin/optional/sso.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,3 +12,65 @@ This page is under construction.
For the moment, please refer to [this pull request](https://github.com/mastodon/mastodon/pull/16221)
{{< /hint >}}

# 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`.
Copy link
Contributor

@ThisIsMissEm ThisIsMissEm Jul 25, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


## OpenID Connect
OpenID is configured using these environment variables.
```
OIDC_ENABLED=
OIDC_DISPLAY_NAME=
OIDC_ISSUER=
OIDC_DISCOVERY=
OIDC_CLIENT_AUTH_METHOD
OIDC_SCOPE=
OIDC_RESPONSE_TYPE=
OIDC_RESPONSE_MODE=
OIDC_DISPLAY=
OIDC_PROMPT=
Copy link
Contributor

@ThisIsMissEm ThisIsMissEm Jul 24, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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_SEND_NONCE=
OIDC_SEND_SCOPE_TO_TOKEN_ENDPOINT=
OIDC_IDP_LOGOUT_REDIRECT_URI=
Copy link
Contributor

@ThisIsMissEm ThisIsMissEm Jul 25, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This can be used in combination with OIDC_END_SESSION_ENDPOINT to redirect the user back to Mastodon after they have signed out.

OIDC_UID_FIELD=
OIDC_CLIENT_ID=
OIDC_REDIRECT_URI=
OIDC_HTTP_SCHEME=
OIDC_HOST=
OIDC_PORT=
OIDC_AUTH_ENDPOINT=
OIDC_TOKEN_ENDPOINT=
OIDC_USER_INFO_ENDPOINT=
OIDC_JWKS_URI=
OIDC_END_SESSION_ENDPOINT=
OIDC_SECURITY_ASSUME_EMAIL_IS_VERIFIED=
```

Many of these variables can be omitted if the identity provider supports discovery using `OIDC_DISCOVERY=true`.

With that variable set, the environment variables that have to be configured are:
```
OIDC_ENABLED=true
OIDC_ISSUER=<URI to IdP> # For Keycloak, this is the realm's URI.
OIDC_DISCOVERY=true
Copy link
Contributor

@ThisIsMissEm ThisIsMissEm Jul 25, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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_DISPLAY_NAME=My SSO # this is the name of the login method displayed to the users. Change as you wish.
OIDC_UID_FIELD=preferred_username # Keycloak specific, may vary for your identity provider.
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.
Comment on lines +59 to +62
Copy link
Contributor

@ThisIsMissEm ThisIsMissEm Jul 25, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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_SCOPE=openid,profile,email # Keycloak specific, maybe adjusted to your identity provider.
Copy link
Contributor

@ThisIsMissEm ThisIsMissEm Jul 25, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

```

## SAML

## CAS

## Configure SSO as the only authentication method
If you want, you can setup a Mastodon instance and only use external autentication through one of the
methods described above.

After setting up an instance with one of the above authentication providers and setting `OMNIAUTH_ONLY=true`, you may want to add `ONE_CLICK_SSO_LOGIN=true` in your environment variables.
This will replace the two `Sign in` and `Sign up` buttons by a single `Login or Register` button,
redirecting people directly to the SSO provider you configured.