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 table depicts the configuration properties of the TAN REST service:

Topic	Description
Class	ch.nevis.esauth.rest.service.TANService
Logging	REST
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 ".
	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.
Default base path	/tan

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 table lists the HTTP methods available for the REST interface of a TAN service:

Method	Path	MIME response type	Description	Parameters
GET	generate	Application/xml,application/json	Generates a TAN, sends it to the defined recipients and responds to the client with the generated TAN code.	sender " for a detailed description of the channel-specific properties)
POST	generate	See corresponding GET method	See corresponding GET method	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](https://docs.oasis-open.org/security/saml/v2.0/saml-metadata-2.0-os.pdf)". 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 (we only support 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 table describes the SAML metadata service:

Topic	Description
Class	ch.nevis.esauth.rest.service.SAMLMetadataService
Logging	REST
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.
Default base path	/meta/SAML2.0If the default context root has not been changed, the REST service is available under the "/nevisauth/meta/SAML2.0" URL using the GET method.

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 table shows the available HTTP methods for the REST interface of a SAML metadata service:

Method	Path	MIME response type	Description	Parameters
GET	/nevisauth/meta/SAML2.0	application/samlmetadata+xml	Retrieves the metadata of all known entities.
GET	/nevisauth/meta/SAML2.0/{id}	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(https://tools.ietf.org/html/rfc7662) 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 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 table describes the OAuth 2.0 token introspection REST service:

Topic	Description
Class	ch.nevis.esauth.rest.service.tokenintrospection.TokenIntrospectionService
Logging	REST and OAuth2
Properties	authstates AuthStates that are exposed by the token introspection service. If this list does not include the name of a specificAuthorizationServe*r, the service will report all tokens for this authorization server as being invalid.
Default base path	/oauth/introspect

Example

<RESTService name="tokenIntrospection" class="ch.nevis.esauth.rest.service.tokenintrospection.TokenIntrospectionService" path="/oauth/introspect">
 <property name="authstates" value="AuthorizationServer1, AuthorizationServer2"/>
</RESTService>

The following table lists the HTTP methods available for the REST interface of the OAuth 2.0 token introspection service:

Method	Path	Introspection Request	Response content	Description	Parameters
POST	/nevisauth/oauth/introspect/{AuthorizationServerName}	See the Token Introspection specification for details.	See the(https://tools.ietf.org/html/rfc7662#section-2.2) for details.	Retrieves the state of a token for a given AuthorizationServer.	AuthorizationServerName (string, -) The name of the authorization server against which to validate the token (that is, the name of the respective AuthorizationServer AuthState).

Protecting the token introspection service

There are several mechanisms to protect the token introspection service. You can, for example:

• Configure nevisAuth to require 2-way TLS communication (as recommended). If you do so, the protected resource must provide a certificate to access the OAuth 2.0 token introspection service of nevisAuth. The protected resource is the application that wants to check the validity of the tokens.
• Expose the path to /nevisauth/oauth/introspect in nevisProxy and protect it with an IdentityCreationFilter (as any other application that is protected by Nevis).

The RFC 7662 dedicates an entire section to security considerations. For more information, see Security Considerations](https://tools.ietf.org/html/rfc7662#section-4)".

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 has been edited 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
}