OpenID Connect

What Is OpenID Connect?

OpenID Connect is the Authentication Providers type that has the identity of the user verified in an external identity provider (such as Google, Microsoft Entra ID, Apple, Keycloak and Okta). It is an identity layer built on OAuth2: the user is directed to the authorization page of the provider, logs in there and returns to TR7; TR7 takes a token with the authorization code it receives. The password never reaches TR7.

Its difference from OAuth2 is that the provider returns the user identity as a signed ID token. TR7 verifies the signature of this token with the key set of the provider (JWKS) and checks the nonce value against replay attacks; in this way it is guaranteed that the identity information really comes from the provider. If the provider supports it, this type is preferred over OAuth2 for the authentication.

How does it work?

1. An application registration is created on the provider (e.g. the Google Cloud Console, Entra ID); the Client ID and the Client Secret are taken and the Redirect URI address of TR7 is registered.
2. OpenID Connect is selected as the Provider Type on TR7; a built-in provider or Custom Provider is selected in the OAuth Provider field and the client information is entered.
3. The profile is added to the access flow of the vService with AGS enabled as an Authentication Provider step; the user is directed to the provider over the /oauth path.
4. The signature and the nonce value of the ID token are verified; the user information is written to the session attributes with the automatic mapping and the flow continues from the success transition.

Built-in OAuth Provider Catalog

When a built-in provider is selected in the OAuth Provider field, the authorization, token, user information, logout and token revocation addresses, the default scopes and the PKCE and client authentication settings are provided by TR7; the client information (Client ID, Client Secret, OAuth Scopes, Redirect URI), the fields specific to the provider, the logout switches and the ID token fields (JWKS URI, Skip Signature Verification, Skip Nonce Validation) appear in the form. When Custom Provider is selected, all the endpoints are entered manually.

OAuth Provider	Additional field	Logout and revocation switches	Note
e-Devlet	-	Sign Out from Provider on Logout	The scopes are separated with ;; it requires a contract with TÜRKSAT
Google	Hosted Domain, Access Type, Prompt	Revoke Tokens on Logout
Microsoft	Tenant (default common)	Sign Out from Provider on Logout	The Entra ID tenant: common, organizations, consumers or the tenant id or domain name
GitHub	-	-
Apple	Team ID, Key ID, Private Key (.p8)	Revoke Tokens on Logout	It is listed only in this type; the client secret is produced by TR7. There is no user information endpoint; the identity information is read from the ID token and the name of the user is returned only on the first authorization
GitHub Enterprise	GitHub Enterprise Address (required)	-
GitLab	GitLab Address (default https://gitlab.com)	Revoke Tokens on Logout
Keycloak	Realm URL (required)	Revoke and Sign out
Okta	Okta Domain (required)	Revoke and Sign out	PKCE (S256) is on
Auth0	Auth0 Tenant Address (required)	Revoke and Sign out
X (Twitter)	-	Revoke Tokens on Logout	There is no e-mail mapping; PKCE (S256) is on
LinkedIn	-	Revoke Tokens on Logout
Facebook	-	-
Yandex	-	-

The endpoint addresses of the built-in providers are not written to the profile; they are applied from TR7's catalog on every run. The defaults of the fields specific to the provider (e.g. the Microsoft Tenant or the Google Access Type and Prompt), on the other hand, are saved to the profile. Turning the profile into a Custom Provider leaves the address fields empty.

Provider-Specific Fields

When a built-in provider is selected, the fields the provider requires are displayed in the form in place of the address fields:

Field	Provider	Meaning
Tenant	Microsoft	The Entra ID tenant; the default is common.
GitHub Enterprise Address	GitHub Enterprise	The address of the installation; required.
GitLab Address	GitLab	The address of the installation; the default is https://gitlab.com.
Realm URL	Keycloak	The realm address; required.
Okta Domain	Okta	The Okta domain name; required.
Auth0 Tenant Address	Auth0	The tenant address; required.
Hosted Domain	Google	The Google Workspace domain name to which the login is limited.
Access Type	Google	Online (default) or Offline (get refresh token).
Prompt	Google	None, Consent or Select Account (default).
Team ID	Apple	The Apple developer team id; it is 10 characters and it is required.
Key ID	Apple	The id of the Apple signing key; it is required.
Private Key (.p8)	Apple	The content in the -----BEGIN PRIVATE KEY----- block of the Apple signing key; it is required and it does not leave the device. The client secret is produced on every request as an ES256 JWT signed with this key.

Operational Best Practices

• Endpoints by discovery. In Custom Provider the addresses must be filled in with Fetch Endpoints from Issuer instead of being written manually; typing errors break the login flow silently.
• The Redirect URI as a path. When a path (such as /ags-portal/oauth) is written in the Redirect URI field instead of the full address, the same profile works on every domain name of the vService; the address must be registered on the provider side as well.
• The signature verification on. Skip Signature Verification and Skip Nonce Validation must be turned on only for tests or for providers that do not support nonce; they must be kept off in production.
• The lockout on the provider. The lockout is generally performed on the provider side; No Lockout or Use Gateway Defaults must be selected for Lockout Behavior.
• Signing out from the provider on logout too. In environments where shared computers are used, Sign Out from Provider on Logout must be turned on; otherwise the user is let in without being asked for a password on the next login.

How to Add?

A new OpenID Connect provider is added through the TR7 web management interface with the following steps:

1. The Configuration Menu is opened by clicking the TR7 logo at the bottom left.
2. The AGS → Authentication → Authentication Providers → Add steps are followed.
3. A unique and descriptive name is entered for the profile; OpenID Connect is selected as the Provider Type.
4. The OAuth Provider is selected and the client information is entered.
5. The profile is added by clicking the Add button.

Profile Add Form

When the AGS → Authentication → Authentication Providers → Add steps are followed and OpenID Connect is selected in the Provider Type field, the form opens with the following fields.

The Form While OpenID Connect Is Selected (Custom Provider)

The Continuation of the OpenID Connect Form

INFO

Provider Name Required

The name of the profile; it identifies the profile in the list, in the step selection in the flowchart, in the session list and in the logs. The name must be unique on the device; a second profile with the same name is not saved and the Name is used warning is displayed. When it is left empty, the Required field warning is displayed.

INFO

Provider Type Required

The provider type; OpenID Connect is selected on this page. When the type is changed, only the fields of the new type are displayed and saved; the type is changed in the edit form as well.

INFO

Namespace Default: the default route table

The Route Tables record from which the token and user information requests TR7 makes to the provider go out; a route table that has internet access must be selected. The field comes filled with the default route table of the device; the name of this table varies by device (e.g. DEFAULT or DEFAULT_ROUTE).

INFO

OAuth Provider Default: Custom Provider

One of the built-in providers or Custom Provider is selected (see Built-in OAuth Provider Catalog). When a built-in provider is selected, the endpoint addresses, the Fetch Endpoints from Issuer button and the protocol fields (Client Authentication, Enable PKCE, User Info Request Method, User Info Parameters) are hidden. Client ID, Client Secret, OAuth Scopes, Redirect URI, the fields specific to the provider, the logout switches and the JWKS URI, Skip Signature Verification and Skip Nonce Validation fields continue to be displayed.

INFO

Fetch Endpoints from Issuer

The button that appears only while Custom Provider is selected; it fills in the endpoints from the discovery document of the provider (see Fetch Endpoints from Issuer).

INFO

Authorization URL Required (Custom Provider)

The provider endpoint to which the user is directed for the login (such as https://provider.com/oauth/authorize).

INFO

Token URL Required (Custom Provider)

The endpoint at which the authorization code is exchanged for a token.

INFO

User Info URL Required (Custom Provider)

The endpoint at which the user information is read with the access token.

INFO

Logout URL

The logout endpoint of the provider; it is optional. When it is entered, the Sign Out from Provider on Logout switch is displayed.

INFO

Token Revocation URL

The token revocation endpoint of the provider; it is optional. When it is entered, the Revoke Tokens on Logout switch is displayed.

INFO

Client ID Required

The client id of the application registered on the provider.

INFO

Client Secret

The secret key of the application registered on the provider; it is entered in a masked field and is shown as ******** in the preview. In public clients (Client Authentication: Public client — no client secret sent) it is left empty.

INFO

OAuth Scopes

The scopes to be requested are entered separated with a space (openid email profile); in e-Devlet they are separated with ;. For the built-in providers the default scopes are defined in the catalog; when the field is filled in, the entered value is used.

INFO

Redirect URI Required

The address to which the provider sends the user back. The full address or only the path (such as /ags-portal/oauth) is entered; when a path is entered, the address is completed with the scheme and the domain name the request came from. The same address must also be written into the application registration on the provider side.

INFO

Client Authentication Default: client_secret_post

It appears only in Custom Provider. How the client credentials are sent to the token endpoint is selected:

Option	Meaning
Credentials in request body — client_secret_post (default)	The id and the secret key are sent in the request body.
HTTP Basic header — client_secret_basic	The id and the secret key are sent in the Authorization: Basic header.
Public client — no client secret sent	The secret key is not sent; for public clients such as mobile and single-page applications, usually together with PKCE.

INFO

Enable PKCE Default: Disabled

It appears only in Custom Provider. When it is turned on, PKCE protection against the interception of the authorization code is applied.

PKCE Challenge Method Default: SHA256 (Recommended)

Displayed only while Enable PKCE is on.

Option	Meaning
SHA256 (Recommended)	The verifier is hashed with SHA256 and sent.
Plain (Not Recommended)	The verifier is sent without being hashed; only for providers that do not support SHA256.

INFO

User Info Request Method Default: GET with Bearer header (default)

It appears only in Custom Provider. How the user information endpoint is called is selected:

Option	Meaning
GET with Bearer Header (default)	The token is sent in a GET request with the Authorization: Bearer header.
POST Form Parameters	The information is sent as form parameters in a POST request.

INFO

User Info Parameters Default: Disabled

When the switch is turned on, the Parameter Name and Parameter Value table for the additional parameters to be added to the user information request is displayed; both fields are required on each row and the Parameter Name values do not repeat. The parameters are added to the query string in GET and to the form body in POST. The {accessToken}, {clientId}, {clientSecret} and {scope} placeholders are used in the values.

INFO

Revoke Tokens on Logout Default: Disabled

It appears while a token revocation address is defined. While it is on, the tokens of the session are sent to the revocation endpoint of the provider while the session is being closed; if the provider does not respond, the logout is still completed.

INFO

Sign Out from Provider on Logout Default: Disabled

It appears while a logout address is defined. While it is on, the browser is directed to the logout address of the provider after the local session is closed; while it is off, the user is let in without being asked for a password on the next login because the session on the provider is still open.

INFO

JWKS URI

The address of the key set (JSON Web Key Set) at which the signature of the ID token is verified (such as https://provider.com/.well-known/jwks.json). It is filled in with Fetch Endpoints from Issuer. Although the field appears empty in the built-in providers, the address comes from TR7's catalog; the catalog keeps the key address of each provider in its own form (e.g. Keycloak {tenant}/protocol/openid-connect/certs, Okta {tenant}/oauth2/v1/keys, Auth0 {tenant}/.well-known/jwks.json, GitLab {tenant}/oauth/discovery/keys). In Custom Provider, when the field is left empty, the address is derived from the issuer address; if the derived address differs from the real key address of the provider, the signature cannot be verified, so the field must be filled in manually or by discovery.

INFO

Skip Signature Verification Default: Disabled

While it is on, the signature of the ID token is not verified. It is used only for tests made with self-signed tokens; it must be kept off in production.

INFO

Skip Nonce Validation Default: Disabled

While it is on, the nonce check that provides the replay attack protection is not performed. It is turned on for providers that do not return the nonce value in the ID token (such as LinkedIn).

User Attribute Mapping

INFO

Custom User Attribute Mapping Default: No customisation

How the fields in the provider response are mapped to the session attributes is managed. The information bar to the left of the field shows the number of fields mapped automatically for the selected provider; in Custom Provider this number is 15: 15 fields are filled in automatically for this provider. In the built-in providers the number varies (e.g. Google 8, e-Devlet 9, GitHub 6, X 4). When the arrow icon on the bar is clicked, the automatically mapped rows and the JSONata expression of each of them are listed; per row there is a chip that examines the expression in the JSONata workspace and copy operations. In the providers that have no automatic mapping, No automatic mapping for this provider - every attribute has to be mapped below is written on the bar.

When the switch on the right is moved to the Customised position, the AGS Attribute and Source Attribute table is displayed: the session attribute (with a suggestion list) is entered in the left column and the JSONata expression that is evaluated on the provider response in the right column. When the switch is turned on, the + Add link that adds a row appears on the right of the bar. A custom row that targets the same attribute as an automatic row overrides the automatic one (the replaced below badge) and the text of the information bar turns into the … fields are filled in automatically; you replace … of them form, which also says how many automatic rows are replaced. When a name outside the standard attributes of AGS is entered, this attribute is defined as a custom user field on the vService; names that start with _ are considered hidden fields and do not produce a custom user field.

Lockout Configuration

INFO

Lockout Behavior Default: Use gateway defaults

With which lockout policies the failed attempts on this provider are counted is selected:

Option	Meaning
Use Gateway Defaults	The policies in the Default Lockout Policies list of the vService are used.
Replace Defaults	Only the policies selected in the Lockout Policies field are used.
Add to Defaults	In addition to the default policies of the vService, the ones selected in the Lockout Policies field are used as well.
No Lockout	Failed attempts are not counted on this provider, no lockout is performed.

Lockout Policies

Displayed while Replace Defaults or Add to Defaults is selected; the built-in and defined policies on the Account Lockout Policies screen are selected.

INFO

Add

The profile is added by clicking the Add button; the tab closes and the profile is displayed in the list.

Fetch Endpoints from Issuer

The Fetch Endpoints from Issuer button in the form with Custom Provider selected opens a window with the Issuer URL and Route Table fields. /.well-known/openid-configuration is appended to the entered issuer address and the discovery document is taken from the selected route table (the default: the Namespace of the profile); the full .well-known address can also be pasted.

Authorization URL, Token URL and JWKS URI are always filled in; User Info URL, Logout URL and Token Revocation URL are written only if they are announced in the discovery document. The openid profile email scopes the provider announces are added, Enable PKCE (SHA256) is turned on if it is announced, and for Client Authentication the first of client_secret_post, client_secret_basic and none, in that order, among the methods the provider supports is selected.

Addresses that do not start with http:// or https://, addresses that redirect, TR7's own addresses, addresses that return an HTML page, documents that exceed 256 KB and documents that do not carry the authorization_endpoint or the token_endpoint field are rejected; the fetch takes at most 8 seconds. Success is reported with the Endpoint fields were filled from the issuer's discovery document message. The error message starts with Discovery failed:, carries the error coming from the provider and ends with the Tip: enter the provider's identity/issuer address, not its website — it usually starts with accounts., login. or id. hint. The operation is not written to the user operation record.