OAuth 2.0

Use OAuth 2.0 to authenticate users and grant them access to Spinnaker.

OAuth 2.0 is the preferred way to authenticate and authorize third parties access to your data guarded by the identity provider. To confirm your identity, Spinnaker requests access to your email address from your identity provider. Please read ALL of the documentation on this page as just setting the provider may not work for your environment.

Configuration

All of the OAuth 2.0 fields that can be configured in Halyard are detailed here . The documentation on this page frequently refers back to these fields.

OAuth 2.0 providers

Consult the documentation of your OAuth 2 provider to determine the appropriate values to put in each configurable field. For some common OAuth 2.0 providers, specific documentation is provided here.

If you’re using one of these providers, please follow the appropriate link below for specific instructions on configuring your provider:

• Azure
• GitHub Organization
• Google Apps for Work / G Suite
• Oracle Cloud

Network architecture and SSL termination

During the OAuth workflow , Gate makes an intelligent guess on how to assemble a URI to itself, called the redirect URI. Sometimes this guess is wrong when Spinnaker is deployed in concert with other networking components, such as an SSL-terminating load balancer, or in the case of the Quickstart images, a fronting Apache instance.

You can manually set the redirect URI at the security.authn.oauth2.client.preEstablishedRedirectUri field

security:
  authn:
    oauth2:
      client:
        preEstablishedRedirectUri: https://my-real-gate-address.com:8084/login

or via the following hal command:

hal config security authn oauth2 edit --pre-established-redirect-uri https://my-real-gate-address.com:8084/login

Be sure to include the /login suffix at the end of the of your preEstablishedRedirectUri!

Additionally, some configurations make it necessary to “unwind” external proxy instances. This makes the request to Gate look like the original request to the outer-most proxy. Add this to your gate-local.yml file in your Halyard custom profile :

server:
  tomcat:
    protocolHeader: X-Forwarded-Proto
    remoteIpHeader: X-Forwarded-For
    internalProxies: .*

UserInfoMapping

The userInfoMapping field in the configuration is used to map the names of fields from the userInfoUri request to Spinnaker-specific fields. For example, if your user profile in your OAuth 2.0 provider’s system looks like:

{
  "user": "fmercury",
  "mail": "fmercury@queen.com",
  "fName": "Freddie",
  "lName": "Mercury"
}

Then your userInfoMapping should look like:

userInfoMapping:
  email: mail
  firstName: fName
  lastName: lName
  username: user

Restricting access based on User Info

User access can be restricted further based on the user info from an OAuth ID token. This requirement is set via the security.authn.oauth2.userInfoRequirements field, which is a map of key/value pairs. The values are interpreted as regular expressions if they start and end with ‘/’. This enables restricting login to users from a specific domain or having a specific attribute.

For example:

security:
  authn:
    oauth2:
      userInfoRequirements:
        hd: your-org.net
        batz: /^Sample.*Regex/
        foo: bar

To set this field with the Halylard CLI, use equal signs between key and value and repeat the flag to specify multiple values:

hal config security authn oauth2 edit \
  --user-info-requirements hd=your-org.net \
  --user-info-requirements batz=/^Sample.*Regex/ \
  --user-info-requirements foo=bar

Next steps

Now that you’ve authenticated the user, proceed to setting up their authorization .

Troubleshooting

• Review the general authentication workflow .

• Use an incognito window .

• I’m getting an Error: redirect_uri_mismatch from my OAuth provider.

  The full error may look something like:

  Error: redirect_uri_mismatch. The redirect URI in the request, https://some.url/login, does not match the ones authorized for the OAuth client.

  This likely means you’ve not set up your OAuth credentials correctly. Ensure that the Authorized Request URIs list contains “https://my-gate-address/login” (no trailing /).

Azure

Spinnaker supports OAuth 2.0 for authentication with Azure.

G Suite

Spinnaker supports OAuth 2.0 for authentication with G Suite.

GitHub Organizations

Spinnaker supports OAuth 2.0 for authentication with GitHub organizations.

OAuth 2.0 Configuration

Configure your Spinnaker deployment to use OAuth 2.0 for authentication.

Oracle Cloud

Spinnaker supports OAuth 2.0 for authentication with Oracle Cloud OAuth.

Last modified May 7, 2021: docs(migration): fix imgs and links (9a18ce6)