External Identity Provider configuration

The Auth Server uses the OAuth2 protocol to delegate actual authentication to an external IdP which is configured via the idp section of the values.yaml used to deploy the Helm Chart.

Example values.yaml section

#------------------------------------------------------------------------------
# IDP connection details, including secret(s)
#------------------------------------------------------------------------------
idp:
  issuerUrl: "https://your-idp-domain"
  clientName: "enterprise"
  cookieParentDomain: ".your-domain.com"
  superUserIdentifier: "email:admin@your-domain.com"
  existingSecret: "tc-auth-gen-idp-auth"
  usernameClaim: email

issuerUrl

The issuerUrl specifies the Base URL of your IDP, this is used to construct various paths for the OAuth2 protocol used when Auth Server delegates authentication to your IDP. By default three paths are needed and generated from this Base URL:

1. Authorization Path, generated by appending /auth to the given issuerUrl. May be customised by setting the optional authorizationPath key.
2. JWKS Path, generated by appending /jwks to the given issuerUrl. May be customised by setting the optional jwksPath key.
3. Token Path, generated by appending /token to the given issuerUrl. May be customised by setting the optional tokenPath key.

For example if your IdP used non-standard paths for all of the above you might have something like the following in your values.yaml:

idp:
  issuerUrl: "https://your-idp-domain"
  authorizationPath: /custom/auth
  jwksPath: /jwks.json
  tokenPath: /get-token

cookieParentDomain

This configures the domain used in setting the Session cookies that the Auth Server and Telicent applications use to keep track of a users authenticated session. This MUST be set to the parent domain, with a leading ., under which the Auth Server and Telicent applications are deployed otherwise sessions may not be successfully established and maintained.

cookieSecure

The optional cookieSecure key may also be supplied with a boolean value indicating whether or not secure cookies are used. We DO NOT recommend changing this setting from its default.

superUserIdentifier

This key controls which user(s) are treated as super-users and automatically have all roles granted them upon their first login. This is a bootstrapping mechanism to allow the initial administrator to login and configure other users to use the system. It is specified in the form of <selector>:<value> where <selector> is one of the following, these selectors apply to the users information as provided by the external IdP:

Selector	Interpretation
groups:<group>	All members of the given <group> are super-users
email:<email>	The user with the given <email> address is the super-user
userNameAttribute:<username>	The user with the given <username> is the super-user
sub:<subject>	The user with the given <subject> ID is the super-user

Note that a special ALL selector may also be provided that does not require a :<value> portion. This makes all users super-users, we DO NOT recommend the superUserIdentifier being set to this outside development environments.

Modifying superUserIdentifier on a live deployment

The superUserIdentifier is only applied to users logging into Auth Server for the first time as it is only intended as a bootstrapping mechanism for initial installation and setup.

Users who already exist in the Auth Server’s database prior to changing this value are NOT affected by this change, i.e. they DO NOT become super users even if the changed identifier would now target them.

existingSecret

This provides the name of a pre-existing secret containing two keys - clientid and clientsecret. These are used to create an OAuth2 client that allows the Auth Server to delegate authentication to your external IdP.

usernameClaim

This controls which claim, as provided by the external IdP’s user information, is used to populate the username that will be used throughout Core in referring to the user.

The claim chosen here will reflect whether you want to see user-friendly usernames in application logs. For example, configuring this as email, as shown in the earlier example, will show users email addresses alongside their activities in the application logs. If you prefer not to expose this information in your application logs, then you should choose an alternative claim e.g. sub or another suitable claim that your external IdP provides in its User Info responses.