REST service implementations
TAN service
The TAN service is a REST service that sends TAN messages to recipients and responds to the client with the TAN code that it sent to the recipient. This service can access any session parameter when given the SecToken of the user. Alternatively, it can also operate statelessly. The following list depicts the configuration properties of the TAN REST service:
-
Class
ch.nevis.esauth.rest.service.TANService -
Logging
REST -
Default base path
/tan -
Properties
-
tanTemplate(string, "6{ABCDEFGHIJKLMNOPQRSTUVWXYZ}")The template from which the TAN is formed. Defaults to 6 uppercase characters.
-
sender(string, -)Default sender used when the request does not supply
sender. Subject to variable and EL substitution. A requestsenderoverrides this value as given. -
recipient(string, -)Default recipient used when the request does not supply
recipient. Depending on the TAN channel this might be a mobile phone number or an e-mail address. Subject to variable and EL substitution. A requestrecipientoverrides this value as given. -
messageTemplate(string, "MTAN authentication code:${notes:mtan.challenge}")Default message body used when the request does not supply
message. Subject to variable and EL substitution (for example${notes:mtan.challenge}). A requestmessageoverrides this value as given. -
channel(string, "SMTP")The channel used to send the TAN message. Valid channels are "smtp", "aspsmssoap", "ucp", "http", "Swissphone", "null". The channel properties are described in TAN authentication plug-ins.
-
customerField(string, -)This string can only be used with the SwissPhone channel. It is optional. According to the IMASYS specification its maximum length is 254 chars with the "iso-8859-1" charset.
-
rejectUnknownParameters(boolean, "false")Controls how request parameters outside the channel allowlist are handled. Does not apply to
sender,recipient,messageorlang. Whenfalse(default), other unknown parameters are ignored and a warning is written to theRESTlog. Whentrue, the request is rejected with400 Bad Request.
-
<RESTService name="tanService" class="ch.nevis.esauth.rest.service.TANService" path=" /tan">
<property name="rolesAllowed" value="nevisAuth.tanUser"/>
<property name="channel" value="HTTP"/>
<property name="httpUrl" value="http://www.smsbooster.com/send.asp"/>
<property name="httpHeader.Referer" value="https://intranet.nevis.com/sms_service/index.htm"/>
<property name="httpSuccessStatus" value="200-399" />
<property name="httpParam.SMSTelefon" value="${notes:tan.http.receivers}"/>
<property name="httpParam.smsMessage" value="${notes:tan.http.message}"/>
<property name="httpParam.USERID" value="<yourID>" />
<property name="httpProxyHost" value="proxy.nevis.com"/>
<property name="httpProxyPort" value="3128"/>
</RESTService>
The following list shows the HTTP methods available for the REST interface of a TAN service:
-
GETPath:
generateMIME response type:
application/xml,application/jsonGenerates a TAN, sends it to the defined recipients and responds to the client with the generated TAN code.
-
sender(string, -)Overrides the
senderproperty when defined. Taken as given (not subject to variable or EL substitution). -
recipient(string, -)Overrides the
recipientproperty when defined. Taken as given (not subject to variable or EL substitution). -
message(string, -)Overrides the
messageTemplateproperty when defined. Taken as given (not subject to variable or EL substitution). For a body that still needs placeholders such as${notes:mtan.challenge}, set them onmessageTemplateand omit this parameter. -
lang(string, -)Language used when substituting the admin-configured defaults. If this parameter is not set, the default language of the authEngine is selected.
The parameters above (
sender,recipient,message,lang) are always handled by the TAN service. They are not part of the channel allowlist. Variable and EL substitution for these fields applies to the matchingRESTServiceproperties when the request omits them; request values override those defaults as given.In addition, the configured channel may accept a fixed set of request parameters as dynamic send configuration:
- SMTP:
smtpSubject,messageContentType - Other channels (
http, Swissphone,null, …): none (channel behavior is configured on theRESTServiceat init time only)
That set is defined by the channel and is already the full set of request overrides it applies. Other request parameters are ignored, with a
RESTwarning that records how many were ignored and which channel parameters are allowed (caller parameter names and values are not logged), or rejected with400 Bad RequestwhenrejectUnknownParametersistrue.For SMTP, a request
smtpSubjectoverrides the admin-configured subject as given. If it is omitted, the admin SMTP subject on theRESTServiceis used and is subject to variable and EL substitution.messageContentTypeis applied to the outbound mail content type when supplied. See TAN authentication plug-ins for channel configuration details.warningSMTP transport settings (all
mail.*properties, such asmail.smtp.hostormail.transport.protocol) and credentials (smtpUser,smtpPass) are always taken from theRESTServiceconfiguration. If different SMTP settings are required for different callers, configure severalTANServiceinstances on different paths using thepathattribute.noteThe properties
smtpHostandsmtpPortwere deprecated aliases and have been removed. Setting them, as configuration or as a request parameter, has no effect. Usemail.smtp.host/mail.smtp.port(ormail.smtps.host/mail.smtps.portwhen usingsmtps) instead.noteThe TAN service is accessible without authentication unless it is protected. Restrict access by setting the
rolesAllowedproperty on theRESTServiceelement.See TAN authentication plug-ins for a detailed description of the channel-specific properties.
- SMTP:
-
-
POSTPath:
generateMIME response type: See corresponding
GETmethod
SAML metadata service
The SAML metadata service provides a document describing the available IdentityProvider entities for the nevisAuth instance. The service complies with the specification "Metadata for the OASIS SAML V2.0". For details, see Metadata for the OASIS SAML V2.0. The metadata can be used by ServiceProviders, for example if the ServiceProvider supports automatic importing of IdP information. The following information is provided:
- A unique ID that identifies the
idpDescriptor. - The supported protocol (SAML 2.0).
- Public signature and encryption key info material.
- Supported SAML bindings.
- List of issued SAML attributes.
NameIDdescriptions.
The provided metadata will be signed with the configured signer key.
The following list describes the SAML metadata service:
-
Class
ch.nevis.esauth.rest.service.SAMLMetadataService -
Logging
REST -
Default base path
/meta/SAML2.0The REST service is available under the "/nevisauth/meta/SAML2.0" URL using the GET method.
-
Properties
-
state.<name>(string, -)The name of the state of which metadata should be published.
-
signatureKeyInfo(string, "certificate")The content of the keyinfo which should be delivered when requesting SAML metadata.
-
keystoreref(string, "DefaultKeyStore")The keystore which contains the keyobject that should be used to sign the metadata.
-
keyobjectref(string, -)The signer with which the metadata should be signed with.
-
<RESTService name="SAMLMetadataService"
class="ch.nevis.esauth.rest.service.SAMLMetadataService"
path="/rest/samlmeta">
<property name="state.MyIdentityProvider1"
value="https://nevisauth.com/idp1"/>
<property name="state.MyIdentityProvider2"
value="https://nevisauth.com/idp2"/>
<property name="out.keystoreref" value="SAMLMetadataKeyStore"/>
<property name="out.keyobjectref" value="SAMLMetadataSigner"/>
</RESTService>
The following list shows the available HTTP methods for the REST interface of a SAML metadata service:
-
GET/nevisauth/meta/SAML2.0MIME response type:
application/samlmetadata+xmlRetrieves the metadata of all known entities.
-
GET/nevisauth/meta/SAML2.0/{id}MIME response type:
application/samlmetadata+xmlRetrieves metadata by ID (SAML 2.0 Entity Descriptor entity ID). In case of an IdentityProviderState, the entity ID will be the out.issuer parameter by default.
-
id(string, -)The entity ID of a SAML 2.0 Entity Descriptor.
-
OAuth 2.0 token introspection service
The OAuth 2.0 token introspection service as defined in the RFC 7662 is:
[...] a method for a protected resource to query an OAuth 2.0 authorization server to determine the active state of an OAuth 2.0 token and to determine meta-information about this token.
nevisAuth provides this service out-of-the-box. The resource, which is the HTTP client of the service, must provide the name of the authorization server to be used to validate the token. This is the AuthorizationServer AuthState that generates the tokens to protect the resource. The name of the AuthorizationServer AuthState is provided as a path parameter in the URL of the HTTP request.
The following list describes the OAuth 2.0 token introspection REST service:
-
Class
ch.nevis.esauth.rest.service.tokenintrospection.TokenIntrospectionService -
Logging
RESTandOAuth2 -
Default base path
/oauth/introspect -
authstates(string, -)Comma-separated list of names of AuthorizationServer AuthStates that are exposed by the token introspection service. If this list does not include the name of a specific AuthorizationServer, the service will report all tokens for this authorization server as being invalid.
-
authentication(string{"BASIC"}, -)Space-separated list of methods accepted for authentication using the request header. For more information, see OAuth 2.0 Token Introspection above for how to do authentication with the token introspection service.
<RESTService name="tokenIntrospection" class="ch.nevis.esauth.rest.service.tokenintrospection.TokenIntrospectionService" path="/oauth/introspect">
<property name="authstates" value="AuthorizationServer1, AuthorizationServer2"/>
</RESTService>
The following list shows the HTTP methods available for the REST interface of the OAuth 2.0 token introspection service:
-
POST/nevisauth/oauth/introspect/{AuthorizationServerName}Retrieves the state of a token for a given AuthorizationServer.
See the Token Introspection specification for details.
-
AuthorizationServerName(string, -)The name of the authorization server against which to validate the token (that is, the name of the respective AuthorizationServer AuthState).
-
-
POST/nevisauth/oauth/introspect/Retrieves the state of a token for a given AuthorizationServer.
See the Token Introspection specification for details.
infoThis endpoint can only be used when only one AuthorizationServer AuthState is configured in the RESTService
Protecting the token introspection service
For more information on how to protect token introspection service, see the chapter Protecting the nevisAuth REST services.
RFC 7662 dedicates an entire section to security considerations. For more information, see OAuth 2.0 Token Introspection.
Authentication with introspection service
nevisAuth supports the Basic Authorization header with a combination of clientID (the username) and clientSecret (the password).
In case of
-
confidential client: both
clientIDandclientSecretare required. -
public client
- with password: both clientID and clientSecret are required.
- without password: only clientID is required, password can set empty or any dummy string.
Request and response examples using cURL
-
Example 1 - Invalid refresh token
The following command line example queries nevisAuth. It asks whether the refresh token with value 2YotnFZFEjr1zCsicMWpAA is valid for the AuthorizationServer named authServer. The server answers that the token is not valid.
curl 'https://siven.ch:8991/nevisauth/oauth/introspect/authServer' -i -X POST \--insecure --cert /var/opt/keybox/public/node_keystore.pem:password \-H 'Content-Type: application/x-www-form-urlencoded' \-d 'token=2YotnFZFEjr1zCsicMWpAA&token_type_hint=refresh_token'HTTP/1.1 200 OKDate: Mon, 08 Jul 2019 10:15:18 GMTContent-Type: application/jsonContent-Length: 17{"active": false} -
Example 2 - Valid access token
The following command line example queries nevisAuth. It asks whether an access token is valid for the AuthorizationServer named sivenAuthServer. The client does not provide any information on the token type (there is no attribute token_type_hint). The server answers that the token is valid and provides some additional information (note that the output of the cURL command line is modified for the sake of clarity):
curl 'https://siven.ch:8991/nevisauth/oauth/introspect/sivenAuthServer' -i -X POST \--insecure --cert /var/opt/keybox/public/node_keystore.pem:password \-H 'Content-Type: application/x-www-form-urlencoded' \-d 'token=eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAtMjU2In0.eiIwgVmejF087iqtrXjQ-xvRByUVyNuiHpxZn5VUfKuW1U3NP8EtSjnGfrcYm7M-uzdaUxmOwAD_c_PerHjPEpERQ91uxCACPQiY23IyzJKaPp9QByRptZLdyd8cwSg4u5OBAq9R1RDO4vTdHpn5E8K7jmQILXnASC_s9DrHsy0.64RgOvcQgqz8Eoff.oKUt3euLvn9AUKuE6IIu62Pz2slX4X68_G6j48B7xb1Bjcti4wIfpuY0Sr8X6KU-miHOY6BTLVUg2hmkzHAX4Mu65HG98UgmiEnOmru5qnzWzXBqOxxUAKSgoo-VZAYrDblSjTDOIZ-Q3n2n_eYDtnh2_lGZEjbGuMRsHhQu-qWoO3I_PSRSh9_w-Aia8XItE0p1tGz4fD7AG8Ox0LQfnA_Lx2an76elVpJFF6ZAFHnR5U1r9DFuFGgBayEi2N8qHiyrSsr214SA_36vpraUaEqg1rKkkIAmt0_QNI9beMAp7HEU-8dUs6ovHniUVkvU-_NkaIuGsddwUjXwSFH0MH70bAP_Y_aTtL5SJa9TMVs7yy31pIg6NCg4OIBABgLlVAa1W3scEb5bXPNSR6O2fPnt0SURi0QRzRJlz778zWYzagqjhtGUoM6nKt1fYdCOwhgvXZajgZHQUBy4FGS_76WTYauXgAVaV_6XbRG4JM9FNZHK1TaiNJiiCu_jDUsQERu9JfLLOHRmB9JhTmLPAxh6Vcx4dd7dkYPH.gbcKRDPaXAGA3fKaXEu8uA'HTTP/1.1 200 OKDate: Mon, 16 Jul 2019 18:11:54 GMTContent-Type: application/jsonContent-Length: 243{"active": true,"client_id": "sdfo2992342335232","username": "michel","scope": "user:read user:write","sub": "1231sdwraewerwee","aud": "https://siven.ch/resource","iss": "https://www.siven.ch","exp": 1563295046,"iat": 1563294446}
OAuth 2.0 token revocation service
The OAuth 2.0 token revocation service as defined in the RFC 7009 is as follows:
[...] allows clients to notify the authorization server that a previously obtained refresh or access token is no longer needed. This allows the authorization server to clean up security credentials.
nevisAuth provides this service out of the box. The resource, which is the HTTP client of the service, has to provide the name of the authorization server to be used to revoke the token. The same AuthorizationServer AuthState that generated the tokens is used to revoke them. The name of the AuthorizationServer AuthState is provided as a path parameter in the URL of the HTTP request.
The following list describes the OAuth 2.0 token revocation REST service:
-
Class
ch.nevis.esauth.rest.service.tokenrevocation.TokenRevocationService -
Logging
RESTandOAuth2 -
Default base path
/oauth/revoke -
Properties
-
authstates(string, -)Comma-separated list of names of AuthorizationServer AuthStates that are exposed by the token revocation service. If this list does not include the name of a specific AuthorizationServer, nevisAuth logs an error and does not start.
-
authentication(string{"BASIC"}, -)Space-separated list of methods that will be accepted for authenticating using the request header. For more information, see RFC 7009 above for how to do authentication with the token revocation service.
-
<RESTService name="tokenRevocation" class="ch.nevis.esauth.rest.service.tokenrevocation.TokenRevocationService" path="/oauth/revoke">
<property name="authstates" value="AuthorizationServer1, AuthorizationServer2"/>
</RESTService>
The following list shows the HTTP methods available for the REST interface of the OAuth 2.0 token revocation service:
-
POST/nevisauth/oauth/revoke/{AuthorizationServerName}Revokes a token of a given AuthorizationServer.
See the RFC 7009 for details.
-
AuthorizationServerName(string, -)The name of the authorization server against which to revoke the token (that is, the name of the respective AuthorizationServer AuthState).
-
-
POST/nevisauth/oauth/revoke/Revokes a token of a given AuthorizationServer.
See the RFC 7009 for details.
This endpoint can only be used when only one AuthorizationServer AuthState is configured in the RESTService
When multiple instances of nevisAuth have the same OAuth2/OIDC flow, you need to set up the MariaDB OOCDs to share revoked token(s) between instances.
JSON Web Key Set (JWKs)
The OAuth 2.0 JSON Web Key Set as defined in the RFC 7517 is:
[...] JWKs and JWK Sets are used in the JSON Web Signature [JWS] and JSON Web Encryption [JWE] specifications.
nevisAuth provides this service out of the box. The resource, which is the HTTP client of the service, has to provide the name of the authorization server to be used to expose the JWKs.
The following list describes the JWKs service:
-
Class
ch.nevis.esauth.rest.service.jsonwebkey.JWKSService -
Logging
RESTandOAuth2 -
Default base path
/.well-known/jwks.json -
Properties
-
authstates(string, -)Comma-separated list of names of AuthorizationServer AuthStates that are exposed by the JWKs. If this list does not include the name of a specific AuthorizationServer, nevisAuth logs an error and does not start.
-
<RESTService name="jwks" class="ch.nevis.esauth.rest.service.jsonwebkey.JWKSService" path="/.well-known/jwks.json">
<property name="authstates" value="AuthorizationServer1, AuthorizationServer2"/>
</RESTService>
The following list shows the HTTP methods available for the REST interface of the JWKs service:
-
GET/nevisauth/.well-known/jwks.jsonGet JWKs of a given AuthorizationServer.
See the JWKs RFC for details.
OAuth 2.0 Authorization Server Metadata
The OAuth 2.0 Authorization Server Metadata as defined in the RFC 8414 is:
[...] The metadata for an authorization server is retrieved from a well-known location as a JSON [RFC8259] document, which declares its endpoint locations and authorization server capabilities.
nevisAuth provides this service out-of-the-box. The resource, which is the HTTP client of the service, must provide the name of the authorization server and necessary endpoints to be used to expose the Authorization Server Metadata.
The following list describes the Authorization Server Metadata:
-
Class
ch.nevis.esauth.rest.service.oauthdiscovery.DiscoveryService -
Logging
RESTandOAuth2 -
Default base path
/.well-known/openid-configuration -
Properties
-
authstate(string, -)AuthState that contains the information to be used by the Authorization Server Metadata (for example, scopes, grant_type, response_type, and so on). If it is not the name of an existing AuthorizationServer, nevisAuth will log an error and will not start.
-
issuer(string: URI, -)The authorization server's issuer identifier, which is a URL that uses the "https" scheme and has no query or fragment components. If this property is not set, the Issuer will be automatically extracted from the AuthorizationServer AuthState. If no issuer is found neither from the AuthorizationServer nor from the configuration, nevisAuth will show an error.
-
authorizationEndpoint(string: URI, -)URL of the authorization server's authorization endpoint RFC6749. This is REQUIRED unless no grant types are supported that use the authorization endpoint (authorization code grant and implicit grant are using authorization endpoint).
-
tokenEndpoint(string: URI, -)URL of the authorization server's token endpoint RFC6749. This is REQUIRED unless only the implicit grant type is supported.
-
registrationEndpoint(string: URI, -)URL of the authorization server's OAuth 2.0 Dynamic Client Registration endpoint. (more info)
-
jwksService(string, -)Name of the JWKs Service. If this property is configured, the jwks_uri will be automatically generated using the nevisAuth root context.
-
jwksUri(string: URI, -)URL of the authorization server's JWK Set JWK document. If this property is not set, the jwks_uri will be automatically extracted from the jwksService configured above.
-
revocationService(string, -)Name of the Revocation Service. If this property is configured, the revocation_endpoint will be automatically generated using the nevisAuth root context.
-
revocationEndpoint(string: URI, -)URL of the authorization server's OAuth 2.0 revocation endpoint RFC7009. If this property is not set, the revocation_endpoint will be automatically extracted from the revocationService configured above.
-
introspectionService(string, -)Name of the Introspection Service. If this property is configured, the introspection_endpoint will be automatically generated using the nevisAuth root context.
-
introspectionEndpoint(string: URI, -)URL of the authorization server's OAuth 2.0 introspection endpoint RFC7662. If this property is not set, the introspection_endpoint will be automatically extracted from the introspectionService configured above.
-
parService(string, -)Name of the PAR Service. If this property is configured, the pushed_authorization_request_endpoint will be automatically generated using the nevisAuth root context.
-
parEndpoint(string: URI, -)URL of the authorization server's OAuth 2.0 Pushed Authorization Request Endpoint RFC9126. If this property is not set, the pushed_authorization_request_endpoint will be automatically extracted from the parService configured above.
-
userinfoEndpoint(string: URI, -)URL of the authorization server's OAuth 2.0 UserInfo Endpoint.
-
endSessionService(string, -)Name of the end-session service. If this property is configured, the end_session_endpoint is generated from the local host name and the nevisAuth root context. Behind nevisProxy, set
endSessionEndpointinstead. -
endSessionEndpoint(string: URI, -)URL of the end-session endpoint of the authorization server. If this property is not set, the end_session_endpoint is extracted from the endSessionService configured above. If neither is set, the discovery document contains no end_session_endpoint.
-
If the AuthorizationServer enables back-channel logout (openid.bcl.enabled), the discovery document also contains backchannel_logout_supported and backchannel_logout_session_supported with the value true. These values are not configurable on the discovery service.
<RESTService name="discovery" class="ch.nevis.esauth.rest.service.oauthdiscovery.DiscoveryService" path="/.well-known/openid-configuration">
<property name="authstate" value="AuthorizationServer"/>
<property name="issuer" value="https://nevis.net"/>
<property name="authorizationEndpoint" value="https://nevis.net/auth"/>
<property name="tokenEndpoint" value="https://nevis.net/token"/>
</RESTService>
The following list shows the HTTP methods available for the REST interface of the Authorization Server Metadata service:
-
GET/nevisauth/.well-known/openid-configurationGet metadata of a given AuthorizationServer.
See the Authorization Server Metadata
For OpenID Connect, id_token_signing_alg_values_supported contains exactly one algorithm, the default ID token signing algorithm. This algorithm is derived from the key of the AuthorizationServer referenced in authstate: RS256 for an RSA key, and ES256, ES384, or ES512 for an Elliptic Curve key on the P-256, P-384, or P-521 curve. If an Elliptic Curve key is configured, RS256 is not listed. With an RSA key, RS384 and RS512 can be configured per client but are not listed. This intentionally departs from OpenID Connect Discovery 1.0. For the reasons and the impact on relying parties, see Signing algorithm and OpenID Connect conformance.
id_token_encryption_alg_values_supported is not affected, because ID tokens are encrypted with the key of the client.
Pushed Authorization Requests Service
The OAuth 2.0 Pushed Authorization Requests as defined in the RFC 9126 is:
[...] JWT-Secured Authorization Request (JAR) RFC9101 provides solutions for the security challenges by allowing OAuth clients to wrap authorization request parameters in a Request Object, which is a signed and optionally encrypted JSON Web Token (JWT) RFC7519.
To cope with the size restrictions, JAR introduces the request_uri parameter that allows clients to send a reference to a Request Object instead of the Request Object itself.
nevisAuth provides this service out of the box. The resource, which is the HTTPS client of the service, has to provide the name of the authorization server to be used to expose the PAR.
The following list describes the PAR service:
-
Class
ch.nevis.esauth.rest.service.par.PARService -
Logging
RESTandOAuth2 -
Default base path
/par -
Properties
-
authstate(string, -)Name of the AuthorizationServer AuthState that is used for PAR. If this property is not set to the name of a specific AuthorizationServer, nevisAuth logs an error and does not start.
-
lifetime(duration in seconds, 90)Maximum duration in seconds for PAR request URI to be valid. The config value ranges from 5 to 600.
-
authentication(string{"BASIC"}, -)Space-separated list of methods accepted for authentication using the request header.
-
<RESTService name="par" class="ch.nevis.esauth.rest.service.par.PARService" path="/par/">
<property name="authstate" value="AuthorizationServer1"/>
</RESTService>
The following list shows the HTTPS methods available for the REST interface of the PAR service:
-
POST/nevisauth/parSend Authorization Data to PAR Service of a given AuthorizationServer.
See the PAR for details.
OpenID Connect back-channel logout service
The back-channel logout service receives logout tokens from an external OpenID Provider (OP), as defined in OpenID Connect Back-Channel Logout 1.0. nevisAuth acts as relying party: it validates the logout token and ends the matching local sessions. For the concept, see OpenID Connect back-channel logout and RP-initiated logout.
Configure one back-channel logout service for each external OP that nevisAuth trusts, each with its own name and path. Register the URL of the service at the external OP as the back-channel logout URI of nevisAuth.
The following list describes the back-channel logout service:
-
Class
ch.nevis.esauth.rest.service.bclreceiver.BackChannelLogoutReceiverService -
Logging
BclReceiver -
Default base path
/oauth/backchannel_logout -
Requirements
- The
SessionCoordinatorcontains aBackChannelLogoutelement, see OpenID Connect back-channel logout. - Session indexing includes the attributes
ch.nevis.session.rp.oidc.sidandch.nevis.session.rp.oidc.sub. The RelyingPartyState sets these attributes at login.
- The
-
Properties
-
issuer(string, required)The issuer of the external OP. The
issclaim of the logout token must match this value. -
clientId(string, required)The client ID of nevisAuth at the external OP. The
audclaim of the logout token must contain this value. -
jwksUri(string: URI, required)The JSON Web Key Set (JWKS) URI of the external OP. nevisAuth verifies the signature of the logout token with these keys. Only RSA keys are supported.
-
httpclient.*The HTTP client properties for the requests to the
jwksUri, for examplehttpclient.tls.trustStoreRef.
-
<RESTService name="bcl-entra" class="ch.nevis.esauth.rest.service.bclreceiver.BackChannelLogoutReceiverService" path="/oauth/backchannel_logout">
<property name="issuer" value="https://login.microsoftonline.com/<tenant>/v2.0"/>
<property name="clientId" value="nevisauth-client"/>
<property name="jwksUri" value="https://login.microsoftonline.com/<tenant>/discovery/v2.0/keys"/>
</RESTService>
The following list shows the HTTP methods available for the REST interface of the back-channel logout service:
-
POST/nevisauth/oauth/backchannel_logoutReceives a logout token in the form parameter
logout_token(application/x-www-form-urlencoded). nevisAuth responds with HTTP 200 to a valid logout token, also if no matching session exists. nevisAuth responds with HTTP 400 and a JSON error to an invalid logout token. All responses containCache-Control: no-store.
OpenID Connect end-session service
The end-session service implements OpenID Connect RP-Initiated Logout 1.0. An RP redirects the browser of the user to this service to end the session at nevisAuth. The service ends only the session of the user who sends the request. It never ends the sessions of other users. If back-channel logout is configured, the end of the session then triggers back-channel logout to the RPs of the session. For the concept, see OpenID Connect back-channel logout and RP-initiated logout.
The following list describes the end-session service:
-
Class
ch.nevis.esauth.rest.service.endsession.EndSessionService -
Logging
ch.nevis.esauth.rest.service.endsession.EndSessionService -
Default base path
/oauth/end_session -
Requirements
- Session indexing includes the attributes
ch.nevis.session.oidc.sidandch.nevis.session.oidc.sub. - The user authenticated through Nevis and has an authenticated nevisAuth session. nevisAuth verifies the identity of the user with this session before it ends the session.
- The service is exposed through nevisProxy. Protect the path in nevisProxy with an IdentityCreationFilter of the same realm as the authorization endpoint, and delegate the SecToken of the user to nevisAuth. nevisAuth identifies the session of the user with this SecToken. If a request reaches the service without a SecToken, nevisAuth does not end any session, even if the user confirms the logout.
- To accept requests with an
id_token_hint, each AuthorizationServer inauthstatessetsopenid.bcl.enabledtotrue. Otherwise, the ID tokens contain nosidclaim, and nevisAuth rejects requests with anid_token_hint. Requests without anid_token_hintdo not require this property. nevisAuth then shows a confirmation page before it ends the session. See RP-initiated logout without back-channel logout. - If you configure the service with
issuerinstead ofauthstates, the ID tokens contain asidclaim with the ID of the nevisAuth session of the user, or with the value of the session attributech.nevis.session.oidc.sid. If thesidclaim matches neither, nevisAuth asks the user to confirm the logout.
- Session indexing includes the attributes
-
Properties
Configure the service in one of the following ways. You cannot combine them. If you set properties of both ways, or neither, nevisAuth rejects the requests to the service.
- With AuthorizationServers: set
authstates. Use this way if an AuthorizationServer of nevisAuth issues the ID tokens of the RPs. - With an issuer: set
issuer,keystoreref,keyobjectref, and oneclient.<clientId>.postLogoutRedirectUrisproperty for each RP. Use this way if another component issues the ID tokens, but the session of the user exists in nevisAuth. The service then does not use nevisMeta.
In both ways, the
id_token_hintmust be a signed JWT. nevisAuth rejects unsigned and encrypted ID token hints. Theid_token_hintmust contain the claimsiss,sid, andaud. nevisAuth also accepts anid_token_hintthat has expired.-
authstates(string, required withoutissuer)Comma-separated list of the AuthorizationServer AuthStates that the service serves. Each AuthorizationServer must have an
openid.issuerIdand a signing key. nevisAuth uses the AuthorizationServers for the following tasks:- Select the AuthorizationServer by the issuer (
iss) of theid_token_hint. nevisAuth rejects anid_token_hintof another issuer. - Verify the signature of the
id_token_hintwith the keys of the AuthorizationServer, including the previous key if the AuthorizationServer has one for key rotation. - Check the
post_logout_redirect_uriagainst the Post-Logout Redirect URIs of the client. nevisAuth loads the client from the data source of the AuthorizationServer. If the user confirms the logout on the confirmation page, nevisAuth finds the AuthorizationServer by theclient_idparameter. If the request has noclient_id, nevisAuth does not redirect the browser after the confirmation.
- Select the AuthorizationServer by the issuer (
-
issuer(string, required withoutauthstates)The issuer of the ID tokens. The
issclaim of theid_token_hintmust match this value. -
keystoreref(string, required withissuer)The name of the KeyStore that contains the certificate to verify the signature of the
id_token_hint. -
keyobjectref(string, required withissuer)The name of the KeyObject in the
keystorerefKeyStore. The public key of the certificate must be an RSA or EC key. -
keystoreref.oldandkeyobjectref.old(string, optional)The KeyStore and KeyObject of the previous signing key, for key rotation. nevisAuth then also accepts an
id_token_hintthat is signed with the previous key. Set both properties or neither. -
client.<clientId>.postLogoutRedirectUris(string, at least one required withissuer)Space-separated list of the absolute URIs to which nevisAuth may redirect the browser after the logout of the client
<clientId>. Theaudclaim of theid_token_hintmust be the<clientId>. Add one property for each RP. nevisAuth redirects only to apost_logout_redirect_urithat exactly matches one of these URIs. Other properties that start withclient.are not allowed. -
confirmationTemplatePath(string: file path, optional)Path to an HTML template for the logout confirmation page. If not set, nevisAuth shows a built-in page in English. The template can contain the placeholders
${lang},${client_id},${post_logout_redirect_uri},${state},${logout_hint}, and${ui_locales}. It must contain${_csrf}in the confirmation form. nevisAuth reads the template when it handles the first request to the service, and then keeps it in memory.The confirmation form is valid for 10 minutes, and only on the nevisAuth instance that showed it. If several nevisAuth instances serve the end-session service, route the confirmation request to the same instance. If nevisAuth restarts or another instance receives the confirmation, nevisAuth rejects it with HTTP 400, and the user must start the logout at the RP again.
- With AuthorizationServers: set
<RESTService name="end-session" class="ch.nevis.esauth.rest.service.endsession.EndSessionService" path="/oauth/end_session">
<property name="authstates" value="AuthorizationServer"/>
</RESTService>
<RESTService name="end-session" class="ch.nevis.esauth.rest.service.endsession.EndSessionService" path="/oauth/end_session">
<property name="issuer" value="https://op.example.com"/>
<property name="keystoreref" value="IdTokenVerification"/>
<property name="keyobjectref" value="CurrentSigner"/>
<property name="keystoreref.old" value="IdTokenVerification"/>
<property name="keyobjectref.old" value="PreviousSigner"/>
<property name="client.app1.postLogoutRedirectUris" value="https://app1.example.com/logged-out https://app1.example.com/goodbye"/>
<property name="client.app2.postLogoutRedirectUris" value="https://app2.example.com/logged-out"/>
</RESTService>
The following list shows the HTTP methods available for the REST interface of the end-session service:
-
GET/nevisauth/oauth/end_sessionandPOST/nevisauth/oauth/end_session(application/x-www-form-urlencoded)Ends the session of the user. The service accepts the parameters
id_token_hint,client_id,post_logout_redirect_uri,state(at most 2048 characters),logout_hint, andui_locales. nevisAuth redirects only to apost_logout_redirect_urithat exactly matches one of the registered URIs of the client: the Post-Logout Redirect URIs in nevisMeta, or theclient.<clientId>.postLogoutRedirectUrisproperty. If the request contains nopost_logout_redirect_uri, nevisAuth does not redirect the browser.See OpenID Connect RP-Initiated Logout 1.0 for details.
To publish the end-session endpoint in the discovery document, set endSessionService or endSessionEndpoint on the OAuth 2.0 Authorization Server Metadata service.
Session management and termination API
Using the Session management and termination API, you can terminate and remove one or more sessions in nevisAuth. Using the API does not trigger SAML single logout. If OpenID Connect back-channel logout is configured, deleting a session triggers back-channel logout by default (end reason MANAGEMENT_DELETE).
Requirements
The session management and termination API relies on the following mechanisms to work, and keep Nevis cross-component data consistency:
Session indexing
Terminating multiple sessions of the same user relies on the Session indexing feature to identify all sessions, therefore it has to be enabled.
Limitations
- The API can only search by attributes that are listed in the session indexing configuration. Without an attribute name, the API uses the first attribute of the list.
- nevisAuth does not index existing sessions when you add an attribute to the session indexing configuration. These sessions are not found by attribute until they end.
The default index on the loginId attribute is sufficient for most standard use cases.
Terminated session polling
Whenever nevisAuth terminates a session, nevisProxy is not automatically aware. To keep nevisProxy in the loop, the EnablePollTerminatedCalls has to be set to true in the Esauth4ConnectorServlet in the nevisProxy instances connected to the nevisAuth instance. By default, the feature is turned off.
Session Management REST Endpoint
-
Class
ch.nevis.esauth.rest.service.session.ManagementService -
Logging
REST -
Default base path
/management/session
<RESTService name="ManagementService" class="ch.nevis.esauth.rest.service.session.ManagementService" />
The following list shows the HTTP methods available for the REST interface of the nevisAuth session management service:
-
DELETE/nevisauth/management/session/<sessionId>Deletes session based on sessionId.
HTTP status codes:
204OK400Missing input404Missing / invalid session500Error
-
DELETE/nevisauth/management/sessionQuery parameter:
attributeName,attributeValueDeletes sessions based on provided query parameters.
attributeNamehas to match the attributeName used for Session indexing, defaults tologinIdattributeValuethe value used to find sessions
HTTP status codes:
204OK400Missing input404Missing / invalid session500Error
Using wildcards (for example, *) is not supported.
Examples
Terminate a single session based on the sessionId as follows:
curl -k -X DELETE https://<hostname>/nevisauth/management/session/0NmojeOYqnM85xvWcSOrgzUAi9wqImGh7-aSMU9OZl0
Terminate one or more sessions based on attribute value as follows:
curl -k -X DELETE https://<hostname>/nevisauth/management/session?attributeValue=johndoe
Audit logging
Sessions terminated by the session management and termination API generate termination events in the Audit log.
Protect the nevisAuth REST services
You can use the following mechanisms to protect the nevisAuth REST service:
- Configure nevisAuth to require 2-way TLS communication. This is the recommended option.
- Expose the path of the service to nevisProxy, and protect it with an IdentityCreationFilter, just like any other application protected by Nevis.