Zum Hauptinhalt springen

API-LOGIN-v2

Logging in and out​

Qiata uses OAuth2/OpenID Connect as default login mechanism.

warning

We currently support Authorization Code Flow with Proof Key for Code Exchange (PKCE) and Client Credentials Grant

You can use the official certified Relying Party Libraries to implement and ensure you create a secure login flow.

https://openid.net/developers/certified/

You can try to use non certified libraries or implement the login yourself, but keep in mind we cannot support or ensure security this way. You take full responsibility.

Qiata also fulfills the role of beeing a Custom Authorization Server/Identity Provider for OIDC. If you authenticate with OIDC against Qiata, local and LDAP Accounts can be used.

Qiata also offers to configure a third party Authorization Server/remote Identity Provider (IDP). Currently AzureAD and ADFS 4.0 are supported.
If it is configured on your Qiata, you can configure your application to use this Identity Provider. Users can then login with their Microsoft Accounts.

Configuration​

Qiata offers URI Discovery Mechanism for the Provider Configuration URI to provide all informations for the local Identity Provider https://FQDN/.well-known/openid-configuration

Example openid-configuration​

{
    "issuer": "https://demo.secudos.com/",
    "authorization_endpoint": "https://demo.secudos.com/oauth2/auth",
    "token_endpoint": "https://demo.secudos.com/oauth2/token",
    "jwks_uri": "https://demo.secudos.com/.well-known/jwks.json",
    "subject_types_supported": [
        "public"
    ],
    "response_types_supported": [
        "code",
        "code id_token",
        "id_token",
        "token id_token",
        "token",
        "token id_token code"
    ],
    "claims_supported": [
        "sub"
    ],
    "grant_types_supported": [
        "authorization_code",
        "implicit",
        "client_credentials",
        "refresh_token"
    ],
    "response_modes_supported": [
        "query",
        "fragment"
    ],
    "userinfo_endpoint": "https://demo.secudos.com/userinfo",
    "scopes_supported": [
        "offline_access",
        "offline",
        "openid"
    ],
    "token_endpoint_auth_methods_supported": [
        "client_secret_post",
        "client_secret_basic",
        "private_key_jwt",
        "none"
    ],
    "userinfo_signing_alg_values_supported": [
        "none",
        "RS256"
    ],
    "id_token_signing_alg_values_supported": [
        "RS256"
    ],
    "request_parameter_supported": true,
    "request_uri_parameter_supported": true,
    "require_request_uri_registration": true,
    "claims_parameter_supported": false,
    "revocation_endpoint": "https://demo.secudos.com/oauth2/revoke",
    "backchannel_logout_supported": true,
    "backchannel_logout_session_supported": true,
    "frontchannel_logout_supported": true,
    "frontchannel_logout_session_supported": true,
    "end_session_endpoint": "https://demo.secudos.com/oauth2/sessions/logout",
    "request_object_signing_alg_values_supported": [
        "RS256",
        "none"
    ],
    "code_challenge_methods_supported": [
        "plain",
        "S256"
    ]
}

OIDCinfo Endpoint​

On top, a non-standardized endpoint offers additional informations, you may need to configure your application or used libraries.

https://FQDN/v2/oidcinfo

This endpoint only offers the enabled Client-Configurations.

<OClientInfo>
  <Client>
    <Clients>https://login.microsoftonline.com/${tenantID}/v2.0/.well-known/openid-configuration</Clients>
    <IssuerURL>https://login.microsoftonline.com/${tenantID}/v2.0</IssuerURL>
    <ClientName>AzureAD</ClientName>
    <ClientID>${clientID}</ClientID>
    <Scopes>${scopes}</Scopes>
    <GroupClaim>groups</GroupClaim>
    <EmailClaim>email</EmailClaim>
    <Responsetype>code</Responsetype>
    <Prompt/>
    <Max_age/>
    <IsLocal>no</IsLocal>
    <Enabled>yes</Enabled>
    <DisIatVal>yes</DisIatVal>
    <PostLogout>https://demo.secudos.com</PostLogout>
  </Client>
  <Client>
    <Clients>https://demo.secudos.com/.well-known/openid-configuration</Clients>
    <IssuerURL>https://demo.secudos.com/</IssuerURL>
    <ClientName>Qiata</ClientName>
    <ClientID>${clientID}</ClientID>
    <Scopes>${scopes}</Scopes>
    <GroupClaim/>
    <EmailClaim>sub</EmailClaim>
    <Responsetype>code</Responsetype>
    <Prompt>consent</Prompt>
    <Max_age>0</Max_age>
    <IsLocal>yes</IsLocal>
    <Enabled>yes</Enabled>
    <DisIatVal>no</DisIatVal>
    <PostLogout>https://demo.secudos.com</PostLogout>
  </Client>
</OClientInfo>

As an indicator, each client has the isLocal property, to differentiate between Qiatas local IDP and remote IDPs like AzureAD/ADFS.

Other details like ClientID, IssuerURL, postLogoutRedirectURI and required Scopes are also offered.

The property EmailClaim is the Claim Name inside the AccessToken, that must hold the Email Address of the authenticated user. This EmailAddress is used to uniquely identify users.

To further communicate with XMLAPI after successfull authentication you need to pass Access-Token, CSRF-Token and FTAuser Cookie.

Acquire an Access Token and a Refresh Token​

You can use Code Flow with PKCE or client credentials grant if available to get new Tokens.

Code Flow (PKCE)​

info

We recommend, that you use a certified OIDC library.

For Code Flow the required informations can be found in the OIDCinfo Endpoints.

Authority maps to IssuerURL.
RedirectURL is https://QIATAFQDN/v2/login/
PostLogoutRedirectURI maps to PostLogout.

Usually the library then handles Access_Token and refreshing Tokens with Refresh_Token
When you receive the tokens, the response also contains the information how long they are valid.

info

In case of local provider Qiata. The Access_Token is valid for 10 minutes and the Refresh_Token is valid for 15 minutes.
The tokens lifetime of other providers may be different. Check with your provider.

Currently you cannot change RedirectURL or PostLogoutURI.

OIDC Custom App / Client credentials grant​

We also offer the authentication configuration of OIDC client_credentials grant for custom apps.

info

A license key with the feature OpenID Custom App is required.

When authenticating with this client/custom app, it will act on behalf of the selected User Account.
In this case, you will only get Access Tokens and only the local Provider (Qiata) can be used.

Configuration can be done as Primary Company administrator.

New OIDC Provider

Log in to the system as Company Administrator.

  1. Company.

Navigate to the item Company

  1. OpenID Connect Custom App

Navigate to the item OpenID Connect Custom App

  1. OpenID Connect Custom App Configuration

Now fill out the form.
Provide a Name, Client Secret and select the associated User Account. You can type in, to filter the selection.

warning

Keep your Client Secret safe. After saving, the Client Secret is not available in plaintext anymore.

  1. Save

Finally save your configuration.

After some time, the forms provides you with a new ClientID.

warning

If your Client secret got compromised, you should save a new one as soon as possible.
Or Remove the entire configuration. Or shutdown Qiata.

Example POST - Prerequisites to use XMLAPI​

First Step: Receive Access Token​

Provide ClientID and ClientSecret​
curl --request POST \
  --url 'https://QIATAFQDN/oauth2/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grand_type=client_credentials \
  --data client_id=CUSTOMAPP_CLIENTID \
  --data client_secret=CUSTOMAPP_CLIENTSECRET

Second Step: Receive CSRF Cookie and CSRF Token from Body​

curl --request GET \
  --url 'https://QIATAFQDN/v2/csrf' \
  --cookie-jar CSRFCookies
Provide Access Token, CSRFCookies and set xmllogin to true​
curl --request POST \
  --url 'https://QIATAFQDN/v2/qiata' \
  --header "X-CSRF-TOKEN: TOKEN FROM REPSONSE BODY OF STEP2" \
  --cookie CSRFCookies \
  --cookie-jar FTACookie \
  --data "xmllogin=true" \
  --data "at= THE ACCESS TOKEN FROM STEP1"

Acquire a CSRF-Token​

Send a GET request to https://FQDN/v2/csrf

Extract the Cookie csrf_token.

csrf_token=uOCgu8RZHGtsdfN+pt13J6omlBcgOXQNONgn2CvtbSs=;

Use this Token on all POST Requests to https://FQDN/v2 endpoints. The Token can be send in different ways to the endpoint:

  • request header: X-CSRF-Token
  • POST value: csrf_token
  • Cookie: csrf_token

Acquire the FTAUserCookie​

After the OIDC login and before the user can use Qiata functions the user has to be authorized by the Qiata. The authorization returns a Cookie FTAUser, which has to be send with any requests to https://FQDN/v2/fta.

The authorization endpoint is https://FQDN/v2/qiata. Send a POST request with the following values to it:

  • at: the current access token
  • xmllogin: true
  • usersonly: true
  • tkey: notneeded

The Response contains an XML-structure with a status value and a possible errormessage on failure. Within the Response the server has set the Cookie FTAUser.