Skip to main content

nevisadmin-plugin-oauth

Access Token Consumer​

This step can validate access tokens issued by an OAuth 2.0 Authorization Server / OpenID Provider.

You can use this step in the Initial Authentication Flow of a Authentication Realm to provide a simple resource server for REST services.

The access token has to be sent as Bearer token in the Authorization header.

The content of the token will be stored in the session.

No authentication decision is taken! You have to use the session variables in a subsequent step to authenticate the user.

For instance, you may use a nevisIDM User Lookup step to search for a user in nevisIDM.

When the access token is invalid a 403 forbidden will be returned.

This pattern is experimental as there are several limitations. For instance, it is assumed that the authorization server is running Nevis and is set up by a OAuth 2.0 Authorization Server / OpenID Provider pattern which is part of this project. Thus, there are cases where this pattern cannot be used yet. These limitations may be addressed in a future release.

On Success​

Assign a step to continue with after successfully validating the token.

On Missing Token​

Assign a step to continue with when no token was sent.

If nothing is assigned then authentication will fail with an error.

OAuth 2.0 Authorization Server / OpenID Provider​

Assign the OAuth 2.0 Authorization Server / OpenID Provider which has issued the access token.

Note that this step works in combination with Nevis OAuth 2.0 Authorization Server / OpenID Provider only and the other pattern has to be in the same project.

Apple Login Step​

Setup social login, using Apple as OIDC provider.

Client ID​

ClientID is Identifier provided by Apple when you register Apple as IdP service.

Client Secret​

The Client Secret is a JWT token generated by using a private key provided by Apple. Please follow the instructions here.

You can generate the client secret by yourself and configure it here, or upload the Private Key to generate the client secret automatically. Only private key or client secret can be use at the time

Return Path​

The callback URI after successful login with Apple. Default value is /oidc/apple/ This will create an endpoint in your host config. This means the URL will be combination between the host Frontend Address and the Return Path. E.g.

Return Path: /oidc/apple/

Frontend Address: https://nevis.net

The URL will become: https://nevis.net/oidc/apple/

So returnUrls configuration in Apple you need to input https://nevis.net/oidc/apple/

Scope(s)​

Select the request scope(s) for getting user information from Apple. Default scopes is email. Scope openid will be added automatically because Apple is implement based on OpenID protocol.

Virtual Host​

Assign a Virtual Host which shall serve as entry point for the callback from social login provider.

In case your host has

  • 1 address, that address will be used
  • many addresses with
    • 1 https, and many http, the https will be used without warning
    • mix between http and https, the 1st https will be used with warning
    • single scheme (http or https only) the 1st address will be used with warning

E.g.

http://nevis.net
http://nevis-security.net
https://nevis.net
https://nevis-security.net

The https://nevis.net will be used as the host for Apple callback

On Success​

The step executed after a successful authentication. If no step is configured here the process ends with AUTH_DONE.

In case you change this to your custom step(s), you can assign pattern Social Login Final Step as the last step of the Authentication process to redirect back to original URL.

On Failure​

The step that will be executed if the authentication fails. If no step is configured here the process ends with AUTH_ERROR.

In case you change this to your custom step(s), you can assign pattern Social Login Final Failure Step as the last step of the Authentication process to redirect back to original URL.

Private Key​

Private key provided by Apple. Find out more here.

If you upload your private key here and set the Issuer, the pattern will automatically generate the Client Secret.

If you do not want to configure your private key, you have to set the Client Secret instead.

Issuer​

The issuer registered claim identifies the principal that issued the client secret. Since the client secret belongs to your developer team, use your 10-character Team ID associated with your developer account. Find out more here.

nevisIDM​

Choose which nevisIDM instance you want to store the user's information after logged in with social login provider.

Client External ID​

The ExtId of the client in nevisIDM that will be used to store the user

On User Not Found​

Configure the authentication flow to be executed when no user was found and the email provided by social account does not exist. The authentication flow must contain the Social Login Create User pattern if a new user shall be created.

Note: Please select scope email and profile for getting user's information from social account.

On User Found​

Configure the Authentication Flow in case no user with Subject/ID from social account was found but email does exist in nevisIDM. The Authentication Flow must contain:

  • Social Login Link User pattern to link an existing user in IDM with Subject/ID of social account.
  • Social Login Done to end the social login flow after some other action(s).

Note: Please select scope email and profile for getting user's information from social account.

Claims Request​

The claims request parameter. This value is expected to be formatted in JSON and does not accept trailing spaces nor tabs.

User ID Field​

Logged userId will automatically get from social account. But you can change the userId by using this field.

Additional Auth Request Parameters​

Arbitrary additional request parameters used in the authentication request. The property supports variable substitution.

Example:

[paramName]=[paramValue]

Button Label​

Enter the text that should be displayed for the end-user on the social login button, and provide translations for this label on the Authentication Realms.

Facebook Login Step​

Set up social login, using Facebook as OIDC provider.

Client ID​

ClientID is App ID provided by Facebook when you register Facebook as IdP service.

Client Secret​

Client Secret is App Secret provided by Facebook when you register Facebook as IdP service.

Return Path​

The callback URI after successful login with Facebook. Default value is /oauth2/facebook/ This will create an endpoint in your host config. This means the URL will be combination between the host Frontend Address and the Return Path. E.g.

Return Path: /oidc/facebook/

Frontend Address: https://nevis.net

The URL will become: https://nevis.net/oauth2/facebook/

So Valid OAuth Redirect URIs configuration in Facebook you need to input https://nevis.net/oauth2/facebook/

Scope(s)​

Select the request scope(s) for getting user information from Facebook. Default scopes is email.

Scope offline_access won't be used. Facebook removed this scope here

Virtual Host​

Assign a Virtual Host which shall serve as entry point for the callback from social login provider.

In case your host has

  • 1 address, that address will be used
  • many addresses with
    • 1 https, and many http, the https will be used without warning
    • mix between http and https, the 1st https will be used with warning
    • single scheme (http or https only) the 1st address will be used with warning

E.g.

http://nevis.net
http://nevis-security.net
https://nevis.net
https://nevis-security.net

The https://nevis.net will be used as the host for Apple callback

On Success​

The step executed after a successful authentication. If no step is configured here the process ends with AUTH_DONE.

In case you change this to your custom step(s), you can assign pattern Social Login Final Step as the last step of the Authentication process to redirect back to original URL.

On Failure​

The step that will be executed if the authentication fails. If no step is configured here the process ends with AUTH_ERROR.

In case you change this to your custom step(s), you can assign pattern Social Login Final Failure Step as the last step of the Authentication process to redirect back to original URL.

nevisIDM​

Choose which nevisIDM instance you want to store the user's information after logged in with social login provider.

Client External ID​

The ExtId of the client in nevisIDM that will be used to store the user

On User Not Found​

Configure the authentication flow to be executed when no user was found and the email provided by social account does not exist. The authentication flow must contain the Social Login Create User pattern if a new user shall be created.

Note: Please select scope email and profile for getting user's information from social account.

On User Found​

Configure the Authentication Flow in case no user with Subject/ID from social account was found but email does exist in nevisIDM. The Authentication Flow must contain:

  • Social Login Link User pattern to link an existing user in IDM with Subject/ID of social account.
  • Social Login Done to end the social login flow after some other action(s).

Note: Please select scope email and profile for getting user's information from social account.

Claims Request​

The claims request parameter. This value is expected to be formatted in JSON and does not accept trailing spaces nor tabs.

User ID Field​

Logged userId will automatically get from social account. But you can change the userId by using this field.

Additional Auth Request Parameters​

Arbitrary additional request parameters used in the authentication request. The property supports variable substitution.

Example:

[paramName]=[paramValue]

Button Label​

Enter the text that should be displayed for the end-user on the social login button, and provide translations for this label on the Authentication Realms.

Generic Social Login Step​

Use to set up a generic social login, either using OAuth2 or OpenID Connect.

Provider Type​

The provider type of the social account: either OpenID Connect or OAuth2.

Client ID​

The identifier provided by the social account when you register with it as the IdP service.

Client Secret​

The secret of the client ID that has been set in the OAuth/OpenID Connect configuration of the social account.

Return path​

The callback URI to go to after a successful login with the social account. This will create an endpoint in your host config. The URL will be a combination between the host Frontend Address and the Return Path. For example, if we have:

  • Return Path: /oidc/app/
  • Frontend Address: https://nevis.net

Then the URL will become https://nevis.net/oidc/app/.

So the value of the callback URI that write in the configuration of the social account will be https://nevis.net/oidc/app/.

Scope(s)​

The request scope(s) for getting the user information from the social account. The default value is email.

The scope openid will be added automatically if providerType is set to OpenID Connect.

Scope offline_access for generate refresh token.

Virtual Host​

Assign a Virtual Host which shall serve as entry point for the callback from social login provider.

In case your host has

  • 1 address, that address will be used
  • many addresses with
    • 1 https, and many http, the https will be used without warning
    • mix between http and https, the 1st https will be used with warning
    • single scheme (http or https only) the 1st address will be used with warning

E.g.

http://nevis.net
http://nevis-security.net
https://nevis.net
https://nevis-security.net

The https://nevis.net will be used as the host for Apple callback

On Success​

The step executed after a successful authentication. If no step is configured here the process ends with AUTH_DONE.

In case you change this to your custom step(s), you can assign pattern Social Login Final Step as the last step of the Authentication process to redirect back to original URL.

On Failure​

The step that will be executed if the authentication fails. If no step is configured here the process ends with AUTH_ERROR.

In case you change this to your custom step(s), you can assign pattern Social Login Final Failure Step as the last step of the Authentication process to redirect back to original URL.

Client Secret Method​

The method used for authenticating the client. It can be either Basic Authentication or POST. The default value is Basic Authentication.

Response Mode​

The mode used for the responses of the server. It can be either Query or Form POST. The default value is Query.

Provider Endpoint​

The provider endpoint that contains the configuration of the OpenID Connect server. It's required when providerType has the value OpenID Connect.

Authorization Endpoint​

The authorization endpoint of the OAuth2 server. It's required when providerType has the value OAuth2.

Token Endpoint​

The token endpoint of the OAuth2 server. It's required when providerType has the value OAuth2.

User Information Endpoint​

The user information endpoint of the OAuth2 server. It's required when providerType has the value OAuth2.

nevisIDM​

Choose which nevisIDM instance you want to store the user's information after logged in with social login provider.

Client External ID​

The ExtId of the client in nevisIDM that will be used to store the user.

On User Not Found​

Configure the authentication flow to be executed when no user was found and the email provided by social account does not exist. The authentication flow must contain the Social Login Create User pattern if a new user shall be created.

Note: Please select scope email and profile for getting user's information from social account.

On User Found​

Configure the Authentication Flow in case no user with Subject/ID from social account was found but email does exist in nevisIDM. The Authentication Flow must contain:

  • Social Login Link User pattern to link an existing user in IDM with Subject/ID of social account.
  • Social Login Done to end the social login flow after some other action(s).

Note: Please select scope email and profile for getting user's information from social account.

First Name Claim​

The claim that contains the first name of the logged-in user in the social account. The default value is given_name.

Second Name Claim​

The claim that contains the second name of the logged-in user in the social account. The default value is family_name.

Email Claim​

The claim that contains the e-mail of the logged-in user in the social account. The default value is email.

Subject Claim​

The claim that contains the subject of the logged-in user in the social account. The default value is sub.

Claims Request​

The claims request parameter. This value is expected to be formatted in JSON and does not accept trailing spaces nor tabs.

User ID Field​

Logged userId will automatically get from social account. But you can change the userId by using this field.

Additional Auth Request Parameters​

Arbitrary additional request parameters used in the authentication request. The property supports variable substitution.

Example:

[paramName]=[paramValue]

Button Label​

The text that should be displayed for the end-user on the social login button, and provide translations for this label on the Authentication Realms.

Button CSS class​

The css class that apply for the social login button. Ensure that the Login Template used in your realm pattern includes a CSS file which defines the CSS class.

Button Logo Path​

The path to logo file of the social login provider. This path is the path of logo file which you which uploaded at Login template in Realm pattern. E.g:

In the zip file the icon with path /webdata/resources/icons/icon.csv, the input is /icons/icon.csv

Generic nevisMeta Instance Settings​

Use this add-on pattern to set low-level properties in configuration files of a nevisMeta Instance.

Java Opts​

Add additional entries to the JAVA_OPTS environment variable.

Use the expression ${instance} for the instance name.

For instance, you may configure nevisMeta to create a heap dump on out of memory as follows:

-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/var/opt/nevismeta/${instance}/log/

Be aware that this example will not work for Kubernetes as the pod will be automatically restarted on out of memory and the created heap dump files will be lost.

Google Login Step​

Set up social login, using Google as OIDC provider.

Client ID​

ClientID is Client ID provided by Google when you create a OAUTH 2.0 credential in Google.

Client Secret​

Client Secret is Client Secret provided by Google when you create a OAUTH 2.0 credential in Google.

Return Path​

The callback URI after successful login with Google. Default value is /oidc/google/ This will create an endpoint in your host config. This means the URL will be combination between the host Frontend Address and the Return Path. E.g.

Return Path: /oidc/google/

Frontend Address: https://nevis.net

The URL will become: https://nevis.net/oidc/google/

So URIs configuration in Google you need to input https://nevis.net/oidc/google/

Virtual Host​

Assign a Virtual Host which shall serve as entry point for the callback from social login provider.

In case your host has

  • 1 address, that address will be used
  • many addresses with
    • 1 https, and many http, the https will be used without warning
    • mix between http and https, the 1st https will be used with warning
    • single scheme (http or https only) the 1st address will be used with warning

E.g.

http://nevis.net
http://nevis-security.net
https://nevis.net
https://nevis-security.net

The https://nevis.net will be used as the host for Apple callback

Scope(s)​

Select the request scope(s) for getting user information from Google. Default scopes is email.

Scope openid will be added automatically because Google is implement based on OpenID protocol.

Scope offline_access for generate refresh token. This scope will transfer to access_type=offline request parameter for matching with Google spec

On Success​

The step executed after a successful authentication. If no step is configured here the process ends with AUTH_DONE.

In case you change this to your custom step(s), you can assign pattern Social Login Final Step as the last step of the Authentication process to redirect back to original URL.

On Failure​

The step that will be executed if the authentication fails. If no step is configured here the process ends with AUTH_ERROR.

In case you change this to your custom step(s), you can assign pattern Social Login Final Failure Step as the last step of the Authentication process to redirect back to original URL.

nevisIDM​

Choose which nevisIDM instance you want to store the user's information after logged in with social login provider.

Client External ID​

The ExtId of the client in nevisIDM that will be used to store the user

On User Not Found​

Configure the authentication flow to be executed when no user was found and the email provided by social account does not exist. The authentication flow must contain the Social Login Create User pattern if a new user shall be created.

Note: Please select scope email and profile for getting user's information from social account.

On User Found​

Configure the Authentication Flow in case no user with Subject/ID from social account was found but email does exist in nevisIDM. The Authentication Flow must contain:

  • Social Login Link User pattern to link an existing user in IDM with Subject/ID of social account.
  • Social Login Done to end the social login flow after some other action(s).

Note: Please select scope email and profile for getting user's information from social account.

Claims Request​

The claims request parameter. This value is expected to be formatted in JSON and does not accept trailing spaces nor tabs.

User ID Field​

Logged userId will automatically get from social account. But you can change the userId by using this field.

Additional Auth Request Parameters​

Arbitrary additional request parameters used in the authentication request. The property supports variable substitution.

Example:

[paramName]=[paramValue]

Button Label​

Enter the text that should be displayed for the end-user on the social login button, and provide translations for this label on the Authentication Realms.

Microsoft Login Step​

Set up social login, using Microsoft as OIDC provider.

Client ID​

ClientID is Application (client) ID provided by Microsoft when you create an Application Microsoft.

Client Secret​

Client Secret is Client Secret provided by Microsoft when you create an Application Credentials & Secrets in Microsoft.

Return Path​

The callback URI after successful login with Microsoft. Default value is /oidc/microsoft/ This will create an endpoint in your host config. This means the URL will be combination between the host Frontend Address and the URI. E.g.

URL: /oidc/microsoft/

Frontend Address: https://nevis.net

The URL will become: https://nevis.net/oidc/microsoft/

So Redirect URIs configuration in Microsoft you need to input https://nevis.net/oidc/microsoft/

Scope(s)​

Select the request scope(s) for getting user information from Microsoft. Default scopes is email.

Scope openid will be added automatically because Microsoft is implement based on OpenID protocol.

Scope offline_access for generate refresh token.

Virtual Host​

Assign a Virtual Host which shall serve as entry point for the callback from social login provider.

In case your host has

  • 1 address, that address will be used
  • many addresses with
    • 1 https, and many http, the https will be used without warning
    • mix between http and https, the 1st https will be used with warning
    • single scheme (http or https only) the 1st address will be used with warning

E.g.

http://nevis.net
http://nevis-security.net
https://nevis.net
https://nevis-security.net

The https://nevis.net will be used as the host for Apple callback

On Success​

The step executed after a successful authentication. If no step is configured here the process ends with AUTH_DONE.

In case you change this to your custom step(s), you can assign pattern Social Login Final Step as the last step of the Authentication process to redirect back to original URL.

On Failure​

The step that will be executed if the authentication fails. If no step is configured here the process ends with AUTH_ERROR.

In case you change this to your custom step(s), you can assign pattern Social Login Final Failure Step as the last step of the Authentication process to redirect back to original URL.

nevisIDM​

Choose which nevisIDM instance you want to store the user's information after logged in with social login provider.

Client External ID​

The ExtId of the client in nevisIDM that will be used to store the user

On User Not Found​

Configure the authentication flow to be executed when no user was found and the email provided by social account does not exist. The authentication flow must contain the Social Login Create User pattern if a new user shall be created.

Note: Please select scope email and profile for getting user's information from social account.

On User Found​

Configure the Authentication Flow in case no user with Subject/ID from social account was found but email does exist in nevisIDM. The Authentication Flow must contain:

  • Social Login Link User pattern to link an existing user in IDM with Subject/ID of social account.
  • Social Login Done to end the social login flow after some other action(s).

Note: Please select scope email and profile for getting user's information from social account.

Application Type​

The application type that you choose when you create your application in Microsoft. We are supporting 3 types

  • common
  • organizations
  • consumers

Please follow this document to select your application type correctly

Tenant ID​

Enter the Tenant ID of your Azure Active Directory.

This setting is used when Application Type is set to organizations.

Check Microsoft documentation on How to find your Azure Active Directory tenant ID.

Claims Request​

The claims request parameter. This value is expected to be formatted in JSON and does not accept trailing spaces nor tabs.

User ID Field​

Logged userId will automatically get from social account. But you can change the userId by using this field.

Additional Auth Request Parameters​

Arbitrary additional request parameters used in the authentication request. The property supports variable substitution.

Example:

[paramName]=[paramValue]

Button Label​

Enter a label for the social login button.

Translations for this label can be configured in the Authentication Realm pattern.

OAuth 2.0 / OpenID Connect Dynamic Client Registration Endpoint​

Links to a Dynamic Client Registration endpoint for OAuth 2.0 / OpenID Connect.

This pattern does not generate any endpoint, it can only be used to provide information about an external endpoint.

The information is by OAuth 2.0 / OpenID Connect Metadata Endpoint to provide metadata.

Endpoint Path​

Enter the URL of the registration endpoint.

Note that this pattern does not set up a registration endpoint, it just provides information about that endpoint.

The information is then used by the OAuth 2.0 / OpenID Connect Metadata Endpoint to provide metadata.

OAuth 2.0 / OpenID Connect JWKs Endpoint​

Sets up a JWKs endpoint for OAuth 2.0 / OpenID Connect.

Endpoint Path​

If you enter a path the REST service will be generated and exposed on the nevisProxy Virtual Host assigned to the OAuth 2.0 Authorization Server / OpenID Provider.

The prefix exact: is not supported here, enter the path as-is.

If you enter a URL no REST service will be generated. Use this variant if you want to use an external service.

Either way, the information will be used by the OAuth 2.0 / OpenID Connect Metadata Endpoint to provide metadata.

OAuth 2.0 / OpenID Connect Metadata Endpoint​

Sets up a Metadata endpoint for OAuth 2.0 / OpenID Connect.

Endpoint Path​

If you enter a path the REST service will be generated and exposed on the nevisProxy Virtual Host assigned to the OAuth 2.0 Authorization Server / OpenID Provider.

The prefix exact: is not supported here, enter the path as-is.

If you enter a URL no REST service will be generated. Use this variant if you want to use an external service.

Either way, the information will be used by the OAuth 2.0 / OpenID Connect Metadata Endpoint to provide metadata.

OAuth 2.0 / OpenID Connect Pushed Authorization Request Endpoint​

Sets up a Pushed Authorization Request endpoint for OAuth 2.0 / OpenID Connect.

Endpoint Path​

If you enter a path the REST service will be generated and exposed on the nevisProxy Virtual Host assigned to the OAuth 2.0 Authorization Server / OpenID Provider.

The prefix exact: is not supported here, enter the path as-is.

If you enter a URL no REST service will be generated. Use this variant if you want to use an external service.

Either way, the information will be used by the OAuth 2.0 / OpenID Connect Metadata Endpoint to provide metadata.

Protected Endpoint​

Set Basic authentication for REST Service of OAuth 2.0 Authorization Server / OpenID Provider.

When this property is enabled, the request must include Authentication Header. The header is a combination of clientID and clientSecret with base64 encoded

Request Timeout​

Configure how the PAR request shall be valid.

For security reasons, we suggest to keep this duration as low as possible.

If not set, the default in the nevisAuth component (90s) applies.

OAuth 2.0 / OpenID Connect Token Introspection Endpoint​

Sets up a Token Introspection endpoint for OAuth 2.0 / OpenID Connect.

Endpoint Path​

If you enter a path the REST service will be generated and exposed on the nevisProxy Virtual Host assigned to the OAuth 2.0 Authorization Server / OpenID Provider.

The prefix exact: is not supported here, enter the path as-is.

If you enter a URL no REST service will be generated. Use this variant if you want to use an external service.

Either way, the information will be used by the OAuth 2.0 / OpenID Connect Metadata Endpoint to provide metadata.

Protected Endpoint​

Set Basic authentication for REST Service of OAuth 2.0 Authorization Server / OpenID Provider.

When this property is enabled, the request must include Authentication Header. The header is a combination of clientID and clientSecret with base64 encoded

OAuth 2.0 / OpenID Connect Token Revocation Endpoint​

Sets up a Token Revocation endpoint for OAuth 2.0 / OpenID Connect.

Endpoint Path​

If you enter a path the REST service will be generated and exposed on the nevisProxy Virtual Host assigned to the OAuth 2.0 Authorization Server / OpenID Provider.

The prefix exact: is not supported here, enter the path as-is.

If you enter a URL no REST service will be generated. Use this variant if you want to use an external service.

Either way, the information will be used by the OAuth 2.0 / OpenID Connect Metadata Endpoint to provide metadata.

Protected Endpoint​

Set Basic authentication for REST Service of OAuth 2.0 Authorization Server / OpenID Provider.

When this property is enabled, the request must include Authentication Header. The header is a combination of clientID and clientSecret with base64 encoded

OAuth 2.0 / OpenID Connect User Info​

An OAuth 2.0 Authorization Server / OpenID User Info returns information about the authenticated user.

Virtual Host​

Assign a Virtual Host which shall serve as entry point.

Authentication Realm​

Assign a realm which shall be exposed to get user information of an OAuth2 Authorization Server or OpenID Connect Provider.

Endpoint​

Enter the path where the endpoint shall be exposed on nevisProxy.

Signer​

Configure the key material which is used to validate tokens. This signer must be the same signer that use to sign the tokens.

nevisIDM​

Assign a nevisIDM Instance or nevisIDM Connector to get user information.

OAuth 2.0 Authorization Server / OpenID Provider​

An OAuth 2.0 Authorization Server / OpenID Provider can issue tokens for a client, considering the requested scopes, claims, and end user consent.

See AuthorizationServer for details.

The pattern is experimental. We recommend to use it for prototyping configuration only as there may be breaking changes in future versions.

The metadata of OAuth 2.0 clients is managed in nevisMeta. The pattern nevisMeta Web Console should be configured as well.

Virtual Host​

Assign a Virtual Host which shall serve as entry point.

Authorization Path​

This is the path where relying parties redirect the browser to.

Example use cases:

  • OAuth: generate the Access Token with use consent enforced
  • OpenID Connect: generate the Access Token and ID Token with user authentication enforced

Token Path​

The endpoint for exchange authorization code and get token(s) (Access Token and ID Token)

Authentication Realm​

Assign a realm which shall be exposed as an OAuth2 Authorization Server or OpenID Connect Provider.

Signer​

Configure the key material which is used to sign issued codes and tokens.

Access Token Format​

Choose between:

  • JWE: the access token will be encrypted. This is the default. The token is considered opaque and thus resource servers need to call the token introspection endpoint to validate the token.

  • JWS: the access token will not be encrypted. Choose this mode to get a signed token which can be validated without calling the token introspection endpoint. A JWKS endpoint will be added to this pattern in 2022.

OpenID Connect​

If enabled the scope openid is allowed for this client.

OpenID Connect Issuer​

Enter the issuer for OpenID Connect.

The value must be a case-sensitive URL using the https scheme that contains at least scheme and host. The port number and path component are optional. No query or fragment components are allowed.

If not set the issuer will be calculated based on:

  • the first Frontend Address with scheme https of the assigned Virtual Host
  • the first Frontend Path

Access Token Claims​

Configure additional claims for the OAuth2.0 Access Token.

Claims are added if they have a value.

For instance, claims may be added when a certain scope is requested which includes them.

OpenID Connect defines the following scope values which may be requested to get claims:

  • profile. claims: name, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, updated_at.
  • email. claims: email, email_verified
  • address. claims: address
  • phone. claims: phone_number, phone_number_verified

Examples:

given_name=${sess:ch.nevis.idm.User.firstName}
family_name=${sess:ch.nevis.idm.User.name}
email=${sess:ch.nevis.idm.User.email}
mobile=${sess:ch.nevis.idm.User.mobile}

ID Token Claims​

Define claims for the OpenID Connect ID token.

For the value you can use a constant, a nevisAuth expression, an EL expression, or refer to an inventory variable by using the ${var.name} syntax.

Note that you also have to do this for standard OpenID Connect claims. The only exception are sub, iss which will always be added.

Here are some examples:

ClaimValue
given_name${sess:ch.nevis.idm.User.firstName}
family_name${sess:ch.nevis.idm.User.name}
email${sess:ch.nevis.idm.User.email}
mobile${sess:ch.nevis.idm.User.mobile}
customer${var.customer-number}

Which claims will be added to the ID token depends on the incoming request. Non-standard claims have to be requested using the claims request parameter. Standard claims are added when a certain OpenID Connect scope is requested:

Requested ScopeAdded Claims
profilename, family_name, given_name, middle_name, nickname, preferred_username, profile, picture, website, gender, birthdate, zoneinfo, locale, updated_at
emailemail, email_verified
addressaddress
phonephone_number, phone_number_verified

nevisIDM Client External ID​

The extId of the client in nevisIDM where the user is stored.

REST Endpoint(s)​

Add extension services for OAuth 2.0 Authorization Server / OpenID Provider

JWK Set Key ID​

When set to enabled a kid header value will be added to issued access and ID tokens.

The value allows the authorization server to explicitly signal a change of key material to recipients.

The meaning of the kid header is slightly different for signed and encrypted tokens.

nevisMeta​

Assign a nevisMeta Instance or nevisMeta Connector.

nevisMeta is used to lookup metadata for the given OAuth2 / OpenID Connect Setup (see Setup ID).

Setup ID​

ID of the nevisMeta setup.

Create your setup via the nevisMeta Web Console.

Then the ID of the setup can be determined. There are several ways to do that:

  • hover over the icon which links to the REST API
  • export the setup and check the exported files
  • Configure a nevisMeta REST Service, login and send a GET to /nevismeta/rest/v2/modules/oauthv2/setups/

Cache Timeout​

Caching of responses from a nevisMeta instance. After this time (in seconds), a response is considered outdated and attempts are made to update it.

Clients​

Assign OAuth 2.0 Client patterns.

Configuration is ignored if nevisMeta is used.

Supported Scopes​

Enter scopes which may be requested by an OAuth 2.0 / OpenID Connect Client.

The scope openid must be allowed when OpenID Connect is used.

nevisIDM​

Assign a nevisIDM Instance or nevisIDM Connector. Required if nevisMeta is not used to store user consent.

Invalid Client​

Configure the step to execute after error when the client sending the request is not registered.

If no step is configured here the process ends and the error will display on UI.

Invalid Redirect URI​

Configure the step to execute after error when the redirect_uri request parameter value is not registered for the client sending the request.

If no step is configured here the process ends and the error will display on UI.

Invalid Authorization Request​

Configure the step to execute after error when the authorization request is invalid. Example:

  • Cannot parse Authorization Request
  • Request response-type mismatch with client configuration
  • Invalid scope
  • Policy not allow
  • PKCE method not support
  • Missing code challenge
  • Plain code challenge

If no step is configured here the process ends and the error will display on UI.

Invalid Token Request​

Configure the step to execute after error when token request is invalid and token error response is about to be issued.

If no step is configured here the process ends and the error response issued and return to the client.

Custom Transitions​

Add or overwrite ResultCond elements in the AuthorizationServer state.

This setting is advanced. Use without proper know-how may lead to incorrect behavior.

If you use this setting, we recommend that you contact Nevis to discuss your use case.

The position refers to the list of Additional Follow-up Steps. The position starts at 1.

Examples:

ResultCondPosition
valid-token-request1
valid-authorization-request2

The following ResultCond elements cannot be overruled by this setting:

  • authenticate:valid-authorization-request
  • stepup:valid-authorization-request
  • server-error
  • invalid-client (configure Invalid Client instead)
  • invalid-redirect-uri (configure invalid Redirect URI instead)
  • invalid-authorization-request (configure Invalid Authorization Request instead)
  • invalid-token-request (configure Invalid Token Request instead)

Custom Follow-up Steps​

Assign follow-up steps.

The order of steps is relevant. The first step in this list has index 1.

You may reference a step in the configuration via the Custom Transitions.

JWK Set Endpoint Trust Store​

Assign a trust store for the outbound TLS connection to JWK Set endpoint for ID Token encryption.

Import the CA certificate of the JWK Set endpoint into this trust store.

Since version 4.38 nevisAuth trusts CA certificates included in the JDK.

Thus, it is not required to configure this.

However, you can still configure a trust store here to be as strict as possible.

JWK Set Endpoint Proxy​

Forward proxy for the connection to the JWK Set endpoint for ID token encryption. Enter the hostname:port here

Example: proxy.your-internal-domain:3128

ID Token Lifetime​

How long the ID token should be valid per default (can be overwritten by the setting of individual client). At most a few minutes are recommended.

Auth Code Lifetime​

How long an authorization code issued by the authorization server should be valid.

Refresh Token Rotation​

Defines if a new Refresh Token is issued together with the Access Token on the Token Endpoint while exchanging a refresh token for a new access token (grant_type=refresh_token).

  • enabled, a new Refresh Token is issued, the existing Refresh token is deleted.
  • disabled, the existing Refresh token is returned and remains valid.

Propagation Scope​

Define propagation scope to store information for following AuthStates. Following are propagated data:

  • Authorization request:
    • oauth2.authorization_request.[requestParameter]
  • Client configuration:
    • oauth2.client.id
    • oauth2.client.metadata.[field]
  • Scope configuration:
    • oauth2.scope.policy.clientCredentialsFlow
    • oauth2.scope.policy.authorizationCodeFlow
    • oauth2.scope.policy.implicitFlow
    • oauth2.scope.policy.refreshTokenRequest
    • oauth2.scope.policy.authenticationRequired
    • oauth2.scope.metadata.[field]

You can find out more information in the output session of AuthorizationServer

The propagated data is intended for logging purposes only, no standard AuthState will use it. But you can access and use with Groovy Script Step.

Note: If your flow has multiple user interactions, use the scope session to ensure that the information is available throughout the flow.

Allowed Origins​

List of URL from where that allow to access the authorization endpoint and token endpoint. If this field does not set, authorization endpoint and token endpoint can be access from everywhere.

Select enabled if you want to ask the user to grant consents for scopes.

Which scopes require consent can be configured in nevisMeta.

Select disabled if you don't have any scopes that require consents, or if you have to do custom consent handling.

Custom Pre-Processing​

Assign a step to apply custom pre-processing logic.

This pre-processing logic is executed on the Authorization Path and Token Path.

You may assign a chain of steps to build a flow. The dispatching will continue when leaving this flow on the happy path.

For On Success exits this works automatically.

However, generic exits (i.e. Additional Follow-up Steps in Generic Authentication Step) must be marked a success exits by assigning the Pre-Processing Done pattern.

Custom Properties​

Configure properties of the nevisAuth AuthorizationServer.

Add or overwrite properties by entering a value.

Remove properties generated by this pattern by leaving the value empty.

Examples:

KeyValue
propagationScopesession
nevismeta.blockClientInterval600

Social Login Create User​

Creates a new account in nevisIDM for the logged-in user.

On Success​

The step executed after a successful authentication. If no step is configured here the process ends with AUTH_DONE.

Note: In order to have profile selection in case account have multiple profiles, you need to use the User Lookup pattern.

Unit External ID​

The ExtId of the unit in nevisIDM that will be used to store the user

ID Generation​

Define how the user extId and profileExtId are generated. Choose between:

  • undefined: the extId and profileExtId will be generated by nevisIDM, and it depends on nevisIDM config that the id will be uuid or in any sequence
  • uuid: the extId and profileExtId will be generated in UUID format by nevisAuth and send to nevisIDM. The newly created user extId and profileExtId will be in UUID format

Social Login Done​

Use this step to terminate On User Found and On User Not Found flows of social login patterns (e.g. Google Login, Apple Login).

The step ensures that the conversation is completed (AUTH_DONE or AUTH_ERROR), and the user is redirected back to the originally requested path.

This step can be omitted when federation is used to access authentication as the caller will be redirected in this case.

In you flow you have to create or link the user. You can use Social Login Link User and Social Login Create User for this.

Status​

Choose how to complete the flow:

  • AUTH_DONE: user is authenticated
  • AUTH_ERROR: session is terminated

In both cases the caller is redirect back to the path before jumping of to the social login provider.

When social login is behind federation (e.g. SAML IDP), AUTH_ERROR will be handled by sending the caller back to the origin (e.g. the SAML SP) with a technical error message.

Use to link to an existing user account.

On Success​

The step executed after a successful authentication. If no step is configured here the process ends with AUTH_DONE.

Note: In order to have profile selection in case account have multiple profiles, you need to use the User Lookup pattern.

nevisMeta Connector​

Use to connect to an existing nevisMeta instance.

Use the pattern only when the instance is not set up by this project.

Ensure that the SecToken trust store of the instance allows the SecToken signers used in this project.

Connection URL(s)​

Enter hostname:port of the nevisMeta instance.

Kubernetes​

This setting is used when deploying to Kubernetes only.

Choose between:

  • disabled: instance running on a VM.

  • same_namespace: service running in the same cluster and namespace.

  • other_namespace: service running in the same cluster but in another namespace.

  • other_cluster: service running in another cluster.

Namespace​

Enter the Kubernetes namespace.

Configuration is required when Kubernetes is set to other_namespace.

nevisMeta Database​

Configures nevisMeta to use a MariaDB database for storing sessions. Assign to nevisMeta Instance as Database.

When deploying to Kubernetes, the database and connection user will be created automatically. The database schema will be migrated automatically when upgrading Nevis on the next deployment.

In classic VM deployment you have to provide an empty database and a schema user. The schema user is used by nevisMeta to populate the database during startup.

Setup instructions can be found in the nevisMeta technical documentation.

Database Type​

Choose between MariaDB and PostgresSQL.

We recommend to use MariaDB as it is supported by all Nevis components that have a database.

Note: PostgresSQL database is only experimental configuration.

Database Host​

Enter the host name of the database service.

The database service must be up when you deploy.

In a classic deployment the Database User and Database Password is used to connect.

In Kubernetes deployment a connection user and password will be generated and the Root Credential will be used to set up the database schema.

Database Name​

Here you can change the name of the database.

The database name only needs to be changed when the database service contains multiple databases.

Root Credential​

Enter the name of a Kubernetes secret which contains the user and password of a database root account.

Required in Kubernetes deployment when Advanced Settings / Database Management is to complete or schema.

This is the default behaviour in Kubernetes.

With complete the secret should contain the following:

username: <root-user
password: <root-password>

If the Database Management is set to schema the root user can be omitted, but the application and schema user has to be specified:

ownerUsername: <some-username>
ownerPassword: <some-password>
appUsername: <some-username>
appPassword: <some-password>

If used with complete the app and owner users will be created with the credentials specified in the secret.

Due to the usage of schemas, it is recommended to create a separate Kubernetes secret for each database pattern with the app and owner credentials when using Oracle or PostgreSQL.

Root Credential Namespace​

Set if the Root Credential is in a different Kubernetes namespace.

Schema User​

The user which will be used to connect to the database and create the schema (tables).

The database must have been created already (CREATE DATABASE) and the user must have CREATE privileges for this database.

Example: umet01

Schema User Password​

The password of the user on behalf of the schema will be created in the database.

Database User​

Database connection user.

This setting is used in the following cases:

  • Classic deployments (VM)
  • In Kubernetes when 'Database Management' (Advanced Settings) is set to 'disabled'.

Database Password​

Password for the database connection user.

This setting is used in the following cases:

  • Classic deployments (VM)
  • In Kubernetes when 'Database Management' (Advanced Settings) is set to 'disabled'.

TLS Encryption​

If enabled the query parameter useSSL=true will be added to enable 1-way TLS.

If no Trust Store is assigned then trustServerCertificate=true will be added to the connection string.

Assignment of a Trust Store is recommended for production use.

Note: PostgresSQL database connection configuration doesn't support TLS connection yet.

Trust Store​

Assign a trust store which provides the CA certificate of the DB endpoint.

Key Store​

Define the key store to use for 2-way HTTPs connections for DB endpoint.

This configuration only accept PEM Key Store pattern configuration.

Noted: This is an experimental configuration

Database Management​

The pattern can set up the database, and it's schema when deploying to Kubernetes.

The complete option, on top of handling the schema migration, will do the initial database preparation like creating the actual database or tablespace in case of oracle, as well as creating the required database users.

The schema option will skip the initial preparation and will only take care of the actual schema migration. This requires the schema owner and the application user credentials to be present in the root credential secret. The root user information can be omitted with this option.

You can select disabled here to opt out. In this case you have to create and migrate the database schema yourself.

This feature is set to recommended by default which aims for the most convenient solution based on the deployment type. In case of Kubernetes deployments, it uses complete. In a classical VM deployment, it will use schema if the pattern allows setting Schema User and Schema Password, otherwise it's disabled.

Connection Parameters​

Enter parameters for the DB connection string.

The default value will be used only when no parameters are entered.

If you want to keep the default parameters, add them as well.

Enter 1 parameter per line.

Lines will be joined with &.

Examples (from various Nevis components):

pinGlobalTxToPhysicalConnection=1
useMysqlMetadata=true
autocommit=0

Connection URL​

Set only if you have to use a JDBC connection string which the pattern cannot generate.

If the prefix of the connection string works for you and you only have to add or overwrite query parameters, set Connection Parameters instead.

If you have to use this setting, please consult your setup with your integration partner.

In Kubernetes deployments the connection string configured here is used by the component only. It is not used to set up and migrate the database schema.

Thus, this setting should only be used in classic deployments, or when Database Management is disabled.

nevisMeta Instance​

Represents a nevisMeta instance. The instance is named according to the pattern.

Hint for pattern renaming​

When the 'Instance Name' property is not filled, this pattern uses the pattern's name as instance directory at the target host.

To rename this pattern, follow these steps:

  1. Rename the pattern in the GUI.
  2. Rename the instance directory and associated systemd files on the deployment hosts.
  3. Deploy.

In case step 2 is omitted, the old instance is shut down during deployment.

For more information, see User Guide / Configuration Projects / Working with Patterns.

TCP Service Port​

Port the nevisMeta instance is listening on.

Status Port​

This port is used to check if the instance is up after deployment.

Instance Name​

Enter the instance name.

If not set, the pattern name will be used as the instance name.

When deploying to Kubernetes, this setting will be ignored and the instance name will be default.

Log Settings​

Configure the nevisMeta log files.

Database​

Assign a nevisMeta Database.

Frontend Key Store​

Assign the Key Store for the HTTPs endpoint.

If no pattern is assigned a Key Store will be provided by nevisAdmin 4 automatic key management.

Frontend Trust Store​

Assign the Trust Store for the HTTPs endpoint.

If no pattern is assigned a Trust Store will be provided by nevisAdmin 4 automatic key management.

SecToken Signer Trust Store​

Assign a Trust Store which is used to validate the signature of a received NEVIS SecToken.

There are 2 use cases which require validation:

  • when a user accesses the nevisMeta Web Console the SecToken is signed using NEVIS SecToken / Key Store.
  • when nevisAuth calls nevisMeta the SecToken is signed using nevisAuth Instance / Internal SecToken Signer.

If no pattern is assigned the trust store will be provided by nevisAdmin 4 automatic key management. However, this requires that automatic key management is used in the NEVIS SecToken and nevisAuth Instance patterns.

Client Authentication​

Setting for 2-way TLS on the nevisMeta HTTPs endpoint. There are 3 options will affect the callers (e.g. nevisProxy or technical clients accessing nevisAuth REST APIs)

  • required: Callers must present a client certificate.
  • requested: Callers can present a client certificate.
  • disabled: Callers must not use a client certificate.

The Frontend Trust Store must contain the issuing CA.

Memory Limit​

This setting defines the maximum amount of RAM than can be used by this instance.

VM Deployment​

By default, the Java process will use 1/4 of the available RAM.

Depending on how many instances are deployed to the same target host this may be either too much or too little.

The value configured here will be used for the maximum heap size of the Java process (-Xmx).

Kubernetes Deployment​

In Kubernetes deployment the value configured here will be ignored and the Java process will be configured to use a percentage of the available RAM.

Note that -Xmx is not set to avoid file changes when adapting the limit.

As the docker container runs only 1 process the JVM flags -XX:+UseContainerSupport and -XX:MaxRAMPercentage=80.0 will be applied so that Java process can use up to 80% of the configured limit.

Initial Memory Ratio​

Use the given percentage of Memory Limit for the initial memory usage (-Xms).

This setting applies to classic VM deployments only.

Instance Rename Detection​

During deployment nevisAdmin 4 checks if the instance has been renamed by checking the last metadata file deployed on the target host given the pattern ID.

If instance rename is detected the current instance is stopped.

This check should be disabled if multiple environments are simulated on the same server.

This setting is relevant for classic VM deployment only.

Start Inactive​

In a classic VM deployment the instance is restarted when a configuration file changes that requires a restart. The instance is not restarted when a configuration file changes that does not require a restart.

This setting defines if the instance should also be started when it is down.

This setting applies to classic VM deployment only. In Kubernetes deployment the container pods are always recreated when any configuration file changes.

Check Minimum Version​

Select enabled to perform basic version checks.

In classic VM deployment we run a command on each target host, to check which version of the component is installed.

In Kubernetes deployment we check the version of the docker image instead.

This check can be disabled for testing purposes.

Open Telemetry​

OpenTelemetry is used for several use cases:

  • cross-component tracing in logs
  • exposing metrics

By default, OpenTelemetry is enabled and a Java agent is loaded.

If that Java agent is not present on the machines you are deploying to, then you have to provide it at /opt/agent/opentelemetry-javaagent.jar or select disabled.

Additional Settings​

Assign add-on patterns to customize the behaviour of this nevisMeta instance.

Custom Properties​

Configure properties of the nevisMeta.

Add or overwrite properties by entering a value.

Remove properties generated by this pattern by leaving the value empty.

Examples:

KeyValue
database.migration.automaticfalse

nevisMeta Log Settings​

The pattern defines log levels and log retention of nevisMeta.

Assign to a nevisMeta Instance using Log Settings.

Default Log Level​

Change the level of the root logger. This impacts all logging apart from Log Levels.

Note that Syslog appenders have a threshold which ensures that only INFO, WARN, or ERROR messages are forwarded.

Log Levels​

Configure log levels.

See the nevisMeta Technical Documentation, chapter Logging for details.

Hint: If you only change log levels nevisAdmin 4 does not restart the component in classic VM deployment. The new log configuration will be reloaded within 60 seconds after deployment.

Examples: 

ch.nevis.nevismeta = INFO
ch.nevis.ninja = DEBUG

Rotation Type​

Select log rotation type.

Choose between:

  • size - defines the maximum file size before the log files are rolled over
  • time - defines the time span after which logs are rolled over

If you rotate by time we recommend you monitor the disk usage as log files can be huge.

Note: a combination of size and time based log rotation is not supported.

Max Backup Files​

Maximum number of backup files to keep in addition to the current log file.

This setting applies to nevismeta.log only.

Max File Size​

Maximum allowed file size (in bytes) before rolling over.

Suffixes "KB", "MB" and "GB" are allowed. 10KB = 10240 bytes, etc.

Note: not relevant when rotation type is time.

Rotation Interval​

Rotation interval after which log files are rolled over.

This configuration is not used when Rotation Type is set to size.

Choose between:

  • daily - the postfix of rotated files will be .%d{yyyy-MM-dd}
  • hourly - the postfix of rotated files will be .%d{yyyy-MM-dd-HH}

Log Format​

Log4j 2 log format for the default SERVER logs.

Note: not relevant when Log Targets is set to syslog.

Syslog Format​

Log4j 2 log format for the SERVER SYS logs.

Note: not relevant when Log Targets is set to default.

Regex Filter​

If set, messages for nevismeta.log which match the given regular expression won't be logged.

The regular expression must match the entire line. For instance, you may use the following format to match some text:

.*some text.*

Log Targets​

Select type of log4j appender.

RollingFileAppender and SyslogAppender are possible options.

Syslog Host​

Defines where to send logs to via syslog.

This configuration is used only when syslog forwarding is enabled (see Log Targets).

The syslog facility is localhost3 and the threshold is INFO.

nevisMeta REST Service​

The pattern exposes the nevisMeta REST API on a nevisProxy Virtual Host.

The REST API is exposed on the path /nevismeta/rest.

nevisMeta​

Reference the nevisMeta Instance.

Virtual Host​

Assign a Virtual Host which shall serve as entry point.

Authentication Realm​

Assign a realm pattern which authenticates access to nevisMeta.

Application Access Token​

Assign a NEVIS SecToken pattern.

The token informs nevisMeta about the authenticated user.

If you are not using automatic key management then you also have to configure nevisMeta Instance / NEVIS SecToken Trust so that the signer certificate is trusted.

Additional Settings​

Assign add-on patterns to customize the behaviour of this service.

Example use cases:

  • Authorization Policy to enforce roles or an authentication level.
  • URL Handling to redirect or forward requests.
  • HTTP Header Customization to add, replace, or remove HTTP headers in requests or responses.

nevisMeta Web Console​

Sets up the nevisMeta Web Console, which is a component supporting the setup of OAuth2 and OpenID Connect for nevisAuth.

You can access the Web console on the assigned Virtual Host.

For instance, let's say your domain is example.com, and you have entered https://example.com as a Frontend Addresses in the Virtual Host pattern. This means that you can access the Web console on https://example.com/nevismeta/.

nevisMeta​

Reference the nevisMeta Instance.

Virtual Host​

Assign a Virtual Host which shall serve as entry point.

Trust Store​

Assign the Trust Store provider for outbound TLS connections. If no pattern is assigned a trust store will be provided by nevisAdmin 4 automatic key management.

Hostname Validation​

Enable to verify that the hostname on the certificate presented by the backend matches the hostname of nevisMeta

Key Store​

Assign a key store if you want to use 2-way TLS for the connection between nevisProxy and nevisMeta.

Authentication Realm​

Assign a realm pattern which authenticates access to nevisMeta.

Application Access Token​

A NEVIS SecToken pattern must be assigned here.

The token will be issued after authentication and propagated to nevisMeta.

The user must have the role nevisMeta.admin.

Additional Settings​

Assign add-on patterns to customize the behaviour of this service.

Example use cases:

  • Authorization Policy to enforce roles or an authentication level.
  • URL Handling to redirect or forward requests.
  • HTTP Header Customization to add, replace, or remove HTTP headers in requests or responses.