Authentication API

The Authentication API handles the processes of verifying a user’s identity and managing their session within the system.

Method Endpoint

GET

/cxf/bpc-core/authentication

Description

Check if the user session is valid. This function check the presence of an ssoToken. If a token was found, it is checked on the identity provider. If no token is found or the check was negative 401 "UNAUTHORIZED" will be sent back. If the token was confirmed by the provider 200 OK will be sent.

Returns

The user session as JSON.

HTTP Status Code

  • 200 : OK

  • 401 : Unauthorized

Content-Type

  • application/json

Required Access Rights

Can be used without a user session.

DELETE

/cxf/bpc-core/authentication

Description

Destroys the current user session.

Returns

HTTP Status Code

  • 200 : OK when no user flow identity provider is in use

  • 205 : OK when a user flow identity provider is in use

Required Access Rights

Can be used without a user session.

DELETE

/cxf/bpc-core/authentication/sessions/all

Description

Destroy all user sessions.

Returns

HTTP Status Code

  • 200 : OK

Required Access Rights

The logged in user or API Key must have either the following role or right.

  • Role : USER_ADMIN

  • Right : USER_DELETE_SESSIONS

DELETE

/cxf/bpc-core/authentication/sessions/{sessionId}

Description

Destroys a specific user session.

Path Parameter

sessionId

the non hijackable ID of the user session to destroy

Returns

HTTP Status Code

  • 200 : OK

Required Access Rights

The logged in user or API Key must have either the following role or right.

  • Role : USER_ADMIN

  • Right : USER_DELETE_SESSIONS

POST

/cxf/bpc-core/authentication

Description

Form based login. Forwarding credentials to identity provider. If login was ok, the ssoToken will be placed as cookie in response and the information from provider will be forwarded as JSON.

Consumes

  • application/x-www-form-urlencoded

Returns

The user session as JSON.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

Can be used without a user session.

PUT

/cxf/bpc-core/authentication

Description

Form based update of an existing session with the given tenant name.

Consumes

  • application/x-www-form-urlencoded

Form Parameter

tenantname

the name of the tenant

Returns

The user session as JSON.

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

PUT

/cxf/bpc-core/authentication/language/{lang}

Description

Set the provided language in the user session. When Keycloak is used as IdP, the language gets set in the Keycloak user profile (locale).

Path Parameter

lang

the language to set

Returns

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

Can be used without a user session.

POST

/cxf/bpc-core/authentication/reset

Description

Forwards the provided body to the user self service of the currently used identity provider.

Consumes

  • application/x-www-form-urlencoded

Returns

The response of the user self service

HTTP Status Code

  • 200 : OK

  • 500 : Something wrong with the identity provider settings

Content-Type

  • application/json

Required Access Rights

Can be used without a user session.

POST

/cxf/bpc-core/authentication/changepassword

Description

Form based update of the users password. In case the IdP does not support updating user passwords, the user self service is used.

Form params to provide:

  • username - the name of the user to change the password for

  • oldPassword - the old password

  • newPassword - the new password

Consumes

  • application/x-www-form-urlencoded

Returns

HTTP Status Code

  • 200 : OK

Content-Type

  • application/json

Required Access Rights

A logged in user or API Key is required.

POST

/cxf/bpc-core/authentication/{userName}/impersonate

Description

Impersonate a user. Works only when Keycloak is used as identity provider.

When used with Keycloak one of these Keycloak roles are needed: admin, realm-admin, (manage-users and impersonation)

Path Parameter

userName

the name of the user to impersonate

Returns

The user session as JSON.

HTTP Status Code

  • 200 : OK

  • 500 : Failure due to one of the following reasons:

    • No username given

    • No user session provided

    • Current identity provider does not support impersonation

Content-Type

  • application/json

Required Access Rights

The logged in user or API Key must have either the following role or right.

  • Role : IDENTITY_MANAGER_ADMIN

  • Right : IDENTITY_MANAGER_USER_IMPERSONATE

POST

/cxf/bpc-core/authentication/user/info/{accessTokenType}/token

Description

Get user info by access token. Can only be used with an OpenID Connect provider.

CURL example with 'bearer' as access token type
curl -X POST \
    --header 'X-ApiKey: <YourApiKey>' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'accessToken=<ValueOfTheAccessToken>'  \
    'http://localhost:8181/cxf/bpc-core/authentication/user/info/bearer/token'

Consumes

  • application/x-www-form-urlencoded

Path Parameter

accessTokenType

the type of the given access token. Can be bearer, dpop or mac. Keycloak seems to use 'bearer'.

Form Parameter

accessToken

the access token of the user to get the user info for

Returns

The requested user info as JSON.

HTTP Status Code

  • 200 : OK

  • 500 : Failure due to one of the following reasons:

    • Access token type missing or not supported

    • Access token missing

    • Current identity provider does not support token exchange

Content-Type

  • application/json

Required Access Rights

The logged in user or API Key must have either the following role or right.

  • Role : USER_ADMIN

  • Right : GET_USER_INFO_BY_TOKEN
Press Esc to exit full screen
Modal image placeholder
Press Esc to exit full screen