Okta Authentication Provider
The Backstage core-plugin-api
package comes with a Okta authentication
provider that can authenticate users using Okta OpenID Connect.
Create an Application on Okta
To add Okta authentication, you must create an Application from Okta:
- Log into Okta (generally company.okta.com)
- Navigate to Menu >> Applications >> Applications >>
Create App Integration
- Fill out the Create a new app integration form:
Sign-in method
:OIDC - OpenID Connect
Application type
:Web Application
- Click Next
- Fill out the New Web App Integration form:
App integration name
:Backstage
(or your custom app name)Grant type
:Authorization Code
&Refresh Token
Sign-in redirect URIs
:http://localhost:7007/api/auth/okta/handler/frame
Sign-out redirect URIs
:http://localhost:7007
Controlled access
: (select as appropriate)- Click Save
The configuration examples provided above are suitable for local development. For a production deployment, substitute http://localhost:7007
with the url that your Backstage instance is available at.
Configuration
The provider configuration can then be added to your app-config.yaml
under the
root auth
configuration:
auth:
environment: development
providers:
okta:
development:
clientId: ${AUTH_OKTA_CLIENT_ID}
clientSecret: ${AUTH_OKTA_CLIENT_SECRET}
audience: ${AUTH_OKTA_DOMAIN}
authServerId: ${AUTH_OKTA_AUTH_SERVER_ID} # Optional
idp: ${AUTH_OKTA_IDP} # Optional
# https://developer.okta.com/docs/reference/api/oidc/#scope-dependent-claims-not-always-returned
additionalScopes: ${AUTH_OKTA_ADDITIONAL_SCOPES} # Optional
signIn:
resolvers:
# See https://backstage.io/docs/auth/okta/provider#resolvers for more resolvers
- resolver: emailMatchingUserEntityAnnotation
The values referenced are found on the Application page on your Okta site.
clientId
: The client ID that you generated on Okta, e.g.3abe134ejxzF21HU74c1
clientSecret
: The client secret shown for the Application.audience
: The Okta domain shown for the Application, e.g.https://company.okta.com
authServerId
: The authorization server ID for the Applicationidp
: The identity provider for the application, e.g.0oaulob4BFVa4zQvt0g3
additionalScopes
is an optional value, a string of space separated scopes, that will be combined with the default scope
value of openid profile email offline_access
to adjust the scope
sent to Okta during OAuth. This will have an impact on the dependent claims returned. For example, setting the additionalScopes
value to groups
will result in the claim returning a list of the groups that the user is a member of that also match the ID token group filter of the client app.
Resolvers
This provider includes several resolvers out of the box that you can use:
emailMatchingUserEntityProfileEmail
: Matches the email address from the auth provider with the User entity that has a matchingspec.profile.email
. If no match is found it will throw aNotFoundError
.emailLocalPartMatchingUserEntityName
: Matches the local part of the email address from the auth provider with the User entity that has a matchingname
. If no match is found it will throw aNotFoundError
.emailMatchingUserEntityAnnotation
: Matches the email address from the auth provider with the User entity where the value of theokta.com/email
annotation matches. If no match is found it will throw aNotFoundError
.
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 section of the Sign-in Identities and Resolvers documentation.
Backend Installation
To add the provider to the backend we will first need to install the package by running this command:
yarn --cwd packages/backend add @backstage/plugin-auth-backend-module-okta-provider
Then we will need to add this line:
backend.add(import('@backstage/plugin-auth-backend'));
backend.add(import('@backstage/plugin-auth-backend-module-okta-provider'));
Adding the provider to the Backstage frontend
To add the provider to the frontend, add the oktaAuthApi
reference and
SignInPage
component as shown in
Adding the provider to the sign-in page.