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 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 tokenThe 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
}