Skip to content
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

Jump to bottom

docs: improve github auth providers #24726

Merged
merged 2 commits into from
May 15, 2024
Merged

docs: improve github auth providers #24726

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8c8d36b
docs: improve github auth providers
vinzscam May 10, 2024
8472777
Update docs/auth/github/provider.md
vinzscam May 13, 2024
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
16 changes: 11 additions & 5 deletions docs/auth/github/provider.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,13 +43,12 @@ auth:
# enterpriseInstanceUrl: ${AUTH_GITHUB_ENTERPRISE_INSTANCE_URL}
signIn:
resolvers:
# typically you would pick one of these
- resolver: emailMatchingUserEntityProfileEmail
- resolver: emailLocalPartMatchingUserEntityName
# Matches the GitHub username with the Backstage user entity name.
# See https://backstage.io/docs/auth/github/provider#resolvers for more resolvers.
- resolver: usernameMatchingUserEntityName
```

The GitHub provider is a structure with three configuration keys:
The GitHub provider is a structure with these configuration keys:

- `clientId`: The client ID that you generated on GitHub, e.g.
`b59241722e3c3b4816e2`
Expand All @@ -60,6 +59,9 @@ The GitHub provider is a structure with three configuration keys:
initiating an OAuth flow, e.g.
`https://your-intermediate-service.com/handler`. Only needed if Backstage is
not the immediate receiver (e.g. one OAuth app for many backstage instances).
- `signIn`: The configuration for the sign-in process, including the **resolvers**
that should be used to match the user from the auth provider with the user
entity in the Backstage catalog (typically a single resolver is sufficient).

### Resolvers

Expand All @@ -69,7 +71,11 @@ This provider includes several resolvers out of the box that you can use:
- `emailLocalPartMatchingUserEntityName`: Matches the [local part](https://en.wikipedia.org/wiki/Email_address#Local-part) of the email address from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.
- `usernameMatchingUserEntityName`: Matches the username from the auth provider with the User entity that has a matching `name`. If no match is found it will throw a `NotFoundError`.

> Note: The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.
:::note

The resolvers will be tried in order, but will only be skipped if they throw a `NotFoundError`.

:::

If these resolvers do not fit your needs you can build a custom resolver, this is covered in the [Building Custom Resolvers](../identity-resolver.md#building-custom-resolvers) section of the Sign-in Identities and Resolvers documentation.

Expand Down
Loading