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 stateless. 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, -)

    The sender of the TAN. Can be overridden by query or form parameters.

  • recipient (string, -)

    The recipient of the TAN. Depending on the TAN channel this might be a mobile phone number or an e-mail address. Can be overridden by query or form parameters.

  • messageTemplate (string, "MTAN authentication code: ${notes:mtan.challenge}")

    The message template sent to the recipient. The actual message can be overridden by query or form parameters.

  • 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.

Example

<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:

• GET

  Path: generate

  MIME response type: application/xml,application/json

  Generates a TAN, sends it to the defined recipients and responds to the client with the generated TAN code.

  • sender (string, -)

    The sender of the TAN message. This will override the "sender" property if defined.

  • recipient (string, -)

    The recipient of the TAN message. This will override the "recipient" property if defined.

  • message (string, -)

    The message template of the TAN message that is sent to the recipient through the channel. This will override the "messageTemplate" property if defined.

  • lang (string, -)

    The language of the message template. If this parameter is not set, the default language of the authEngine is selected.

    Furthermore, channel-specific properties can be overridden by handing a parameter with the same name. This works for the following channel-specific properties:

    • smtpSubject
    • smtpHost
    • smtpPort
    • smtpUser
    • smtpPass

    See TAN authentication plug-ins for a detailed description of the channel-specific properties.

• POST

  Path: generate

  MIME response type: See corresponding GET method

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.
• NameID descriptions.

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.0

  The 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.

Example

<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.0

  MIME response type: application/samlmetadata+xml

  Retrieves the metadata of all known entities.

• GET /nevisauth/meta/SAML2.0/{id}

  MIME response type: application/samlmetadata+xml

  Retrieves 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

  REST and OAuth2

• 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. More info how to do authentication with token introspection service here.

Example

<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.

  info

  This 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.

info

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 clientID and clientSecret are 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 OK
  Date: Mon, 08 Jul 2019 10:15:18 GMT
  Content-Type: application/json
  Content-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 OK
  Date: Mon, 16 Jul 2019 18:11:54 GMT
  Content-Type: application/json
  Content-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

  REST and OAuth2

• 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, the nevisAuth logs 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. More info how to do authentication with token revocation service here.

Example

<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

info

When multiple instances of nevisAuth having the same OAuth2/OIDC flow, you need to setup 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

  REST and OAuth2

• 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, the nevisAuth logs error, and does not start.

Example

<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.json

  Get 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

  REST and OAuth2

• Default base path

  /.well-known/openid-configuration

• Properties

  • authstate (string, -)

    AuthState that contains the information to be used by the Authorization Server Metadata (e.g: scopes, grant_type, response_type,...). If it is not the name of an existing AuthorizationServer, the nevisAuth will log error and won't 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.

Example

<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-configuration

  Get metadata of a given AuthorizationServer.

  See the Authorization Server Metadata

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

  REST and OAuth2

• Default base path

  /par

• Properties

  • authstate (string, -)

    Name of AuthorizationServer AuthStates that is using for PAR. 

    If this property does not include the name of a specific AuthorizationServer, the nevisAuth logs error, and does not start.

  • lifetime (duration in seconds, 90)

    Maximum duration in seconds for PAR request URI to be valid. The config value from 5 to 600.

  • authentication (string {"BASIC"}, -)

    Space-separated list of methods accepted for authentication using the request header.

Example

<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/par

  Send Authorization Data to PAR Service of a given AuthorizationServer.

  See the PAR for details.

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 logout in federation use cases.

Experimental feature

API and implementation are likely going to change in the future.

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.

Limitation: Session indexing is configurable for one attribute only. Therefore, the session indexing configuration has to match the attribute used for all other use cases, like the ThrottleSessionsState.

info

The default index on the loginId attribute are 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

Example

<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:

  • 204 OK
  • 400 Missing input
  • 404 Missing / invalid session
  • 500 Error

• DELETE /nevisauth/management/session

  Query parameter: attributeName, attributeValue

  Deletes sessions based on provided query parameters.

  • attributeName has to match the attributeName used for Session indexing, defaults to loginId
  • attributeValue the value used to find sessions

  HTTP status codes:

  • 204 OK
  • 400 Missing input
  • 404 Missing / invalid session
  • 500 Error

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.