Single Sign-On (SSO)¶

Nautobot Cloud Console supports Single Sign-On (SSO) using OAuth2 with three providers: Google, GitHub, Microsoft, or any OIDC-compliant identity provider, simplifying user authentication.

SSO configurations are managed in the Organization Settings SSO tab in the left-hand navigation pane.

List of SSO integrations

Create a new SSO¶

To create a new SSO integration, click the Create button in the top-right corner of the SSO page. A dialog will appear with a form to fill out the details of your new SSO integration.

Dialog prompting the user to create a new SSO integration

Fields¶

Field	Required	Description
Name	Yes	The human-readable name for the SSO integration.
Type	Yes	The type of SSO integration (Google, GitHub, Microsoft).
Description	No	A human-readable description of the SSO integration.
YAML Config	Yes	The YAML configuration for the SSO integration. See YAML Configuration for more details.
Slug	Auto	The string used to reference the SSO within the API. This is auto-generated and cannot be changed once created.

YAML Configuration¶

Before creating a YAML Configuration, you must first create the appropriate project for Google, register an OAuth application for GitHub, or add an app in Application Registration Portal for Microsoft. You will then need the clientID and clientSecret values from the application integration. Below is a sample YAML configuration for two types of authorization

Google¶

clientID: 292085223830.apps.googleusercontent.com
clientSecret: 2d106b111a390d9692ab9a8a295ac05668632b17d6e342d149209eaabf769821
hostedDomains:
  - example.com

name	type	required	meaning
clientID	string	yes	Unique username for an application. To get this value, contact your IT department.
clientSecret	string	yes	Unique secret password for your app that only your app and the authorization server know (256-bit value converted to a hexadecimal representation). To get this value, contact your IT department.
hostedDomains	list of strings	yes	List of domains that can log in using your SSO integration.

GitHub¶

Example using GitHub Organizations¶

clientID: 6779ef20e75817b79602
clientSecret: f61fb2e07ea4c0569d72c94fd2eef75569ef9253a336395072e0c38b1012dd4c
orgs:
  - name: my-organization
  - name: my-organization-with-teams
    teams:
      - red-team
      - blue-team

name: "my-organization" - Include all teams in the organization.
name: "my-organization-with-teams" - An allowed list of teams. Only include group claims for these teams.

Example without orgs field¶

clientID: 6779ef20e75817b79602
clientSecret: f61fb2e07ea4c0569d72c94fd2eef75569ef9253a336395072e0c38b1012dd4c

name	type	required	meaning
clientID	string	yes	clientID is like a unique username for apps. Think of it as a long, unique password, often a string of 32 jumbled letters and numbers. To get this value, contact your IT department.
clientSecret	string	yes	clientSecret is a unique and secret password for your app that only your app and the authorization server know (256-bit value converted to a hexadecimal representation). To get this value, contact your IT department.
orgs	list of dicts	no	If orgs are specified in the config then the user MUST be a member of at least one of the specified orgs to authenticate.

Microsoft¶

Example using Microsoft with scopes and groups¶

clientID: 3d33df33-123f-4rt3-12d9-kc45e88ebcdf
clientSecret: M456X~5kiHOHSl78kftsbhIA1bbgYTs~l12zLaPZ
tenant: networktocode.com
scopes:
  - openid
  - email
groups:
  - developers
  - devops

Example without scopes and groups field¶

clientID: 3d33df33-123f-4rt3-12d9-kc45e88ebcdf
clientSecret: M456X~5kiHOHSl78kftsbhIA1bbgYTs~l12zLaPZ
tenant: networktocode.com

name	type	required	meaning
clientID	string	yes	clientID is a unique name for apps. It is often a string of 32 alphanumeric characters. To get this value, contact your IT department.
clientSecret	string	yes	clientSecret is a unique secret password for your app that only your app and the authorization server know (256-bit value converted to a hexadecimal representation). To get this value, contact your IT department.
tenant	string	yes	Tenant configuration parameter controls what kinds of accounts may be authenticated. To define this, set the tenant parameter to one of the following:• or - only accounts belonging to specific tenant identified by either UUID or domain can authenticate.• common - both personal and business/school accounts can authenticate via Microsoft• customers - only personal accounts can authenticate• organizations - only business/school accounts can authenticate
scopes	list of strings	no	Configuration parameter controls what the initial scope(s) of the identity token. To change this initial set, configure the scopes parameter to be a list of one or more valid scopes (as defined in Microsoft Documentation).The default scope (if one is not specified in the connector’s configuration) is user.read
groups	list of strings	no	If groups are specified in the config then the user MUST be a member of at least one of the specified groups to authenticate.

Generic OIDC¶

Example using Generic OIDC for Cloudflare with all fields¶

clientID: 8c33c3da9e8f392k71m1f9dc1a190cb3707ad27ba4d19bff45c900e6dfet1f4a
clientSecret: 2d106b111a390d9692ab9a8a295ac05668632b17bbb342d149209aaaaa100000
issuer: https://company.cloudflareaccess.com/cdn-cgi/access/sso/oidc/8c33c3da9e8f392k71m1f9dc1a190cb3707ad27ba4d19bff45c900e6dfet1f4a
scopes:
  - profile
  - email
  - groups
insecureSkipEmailVerified: true
insecureEnableGroups: true
getUserInfo: true

Example using Generic OIDC for Cloudflare with only required fields¶

clientID: 8c33c3da9e8f392k71m1f9dc1a190cb3707ad27ba4d19bff45c900e6dfet1f4a
clientSecret: 2d106b111a390d9692ab9a8a295ac05668632b17bbb342d149209aaaaa100000
issuer: https://company.cloudflareaccess.com/cdn-cgi/access/sso/oidc/8c33c3da9e8f392k71m1f9dc1a190cb3707ad27ba4d19bff45c900e6dfet1f4a

name	type	required	meaning
clientID	string	yes	clientID is like a unique username for apps. Think of it as a long, unique password, often a string of 32 jumbled letters and numbers. To get this value, contact your IT department.
clientSecret	string	yes	clientSecret is a unique and secret password for your app that only your app and the authorization server know (256-bit value converted to a hexadecimal representation). To get this value, contact your IT department.
issuer	string	yes	Canonical URL of the provider, also used for configuration discovery. This value MUST match the value returned in the provider config discovery.
scopes	list of strings	no	List of additional scopes to request in token response. Default is profile and email. Full list of scopes
insecureSkipEmailVerified	boolean	no	Some providers return claims without "email_verified" when they did not use email verification in the enrollment process or if they are acting as a proxy for another IDP (e.g., AWS Cognito with an upstream SAML IDP). This can be overridden by setting this option. Default is set to `True`
insecureEnableGroups	boolean	no	Groups claims (like the rest of OIDC claims through Dex) only refresh when the ID token is refreshed, meaning the regular refresh flow doesn't update the groups claim. By default, the OIDC connector doesn't allow groups claims. If you are okay with having potentially stale group claims, you can use this option to enable groups claims through the OIDC connector on a per-connector basis. This can be overridden by setting this option. Default is set to `True`
getUserInfo	boolean	no	When enabled, the OpenID Connector will query the UserInfo endpoint for additional claims. UserInfo claims take priority over claims returned by the IDToken. This option should be used when the IDToken doesn't contain all the claims requested. Default is set to `True`. More information can be found in User Info Documentation