Authorization

The authentication starts by sending the user to the authorization endpoint of Unidy (e.g. <tenant>.unidy.de/oauth/authorize) with required client_id, redirect_uri, response_type and scope parameters.

Note

A list of all OIDC endpoints can be found via the OpenID discovery endpoint at https://demo.unidy.de/.well-known/openid-configuration

Parameter	Content
client_id	Unique identifier that corresponds to one of the UIDs in Unidy's partner Applications (provided by Unidy)
redirect_uri	Endpoint where the data from Unidy should be returned (must be https)
response_type	One of “code”, “token” or “id_token” (the different authentication flows that correspond to the response_type parameter are described later)
scope	Required: openid Optional: email, profile, phone, address If multiple scopes are requested, the param is a list of space (CGI escaped) separated scopes. E.g.: scope=openid+email+profile or scope=openid%20email%20profile

Claims and Scope Mapping

Access to user data is managed via the concept of scopes and claims.

Claims: A claim is a user field or user information that can be acquired. (E.g. birthdate or name).

Scopes: Scopes are used to limit an application's access to a user's account. An application can request one or more scopes, this information is then presented to the user in the consent screen, and the access token issued to the application will be limited to the scopes granted. In OIDC, scopes can also give access to claims. For example, for a partner site to display the full name of a user they would want access to the name claim. To get this name claim, the partner site would need to ask Unidy for the profile scope.

The following table describes the the currently available scopes and their corresponding claims. Unidy is following the OIDC specification for standard claims and scopes as closely as possible.

Scope	Claims	Description
open_id	sub	a users UNIDY_ID
email	email
profile	given_name family_name name gender updated_at birthdate
phone	phone_number
address	formatted, street_address, locality, region, country, postal_code, address_line_1, address_line_2, street, house_number, country_code, company
email_verified	email_verified	indicates whether an email has beed verified
active_membership	active_membership	any active subscription for all the subscription categories
subscriptions:read		allows to read subscriptions from API
subscriptions:write		allows to create, update and delete subscriptions through the API for the authorized user
subscriptions_batch:write		allows to create multiple subscription through the API for the authorized user

Note

The “sub” grant (which is provided by the mandatory open_id scope) is used for identifying the user in the partners website. These subs will be consistent with the legacy fanconnect systems sub.

Note

In addition Unidy can create custom scopes and claims for you. Please reach out to us if you need information which is not included in the list.

An example for a userinfo response/ id_token information:

{
    "sub": "f2a64c72-23ec-4773-a221-b403f6c49ddc", // the unique stable identifier
    "email": "[email protected]",
    "given_name": "Mac",
    "family_name": "Mustermann",
    "name": "Max Mustermann",
    "gender": "male",
    "updated_at": "2020-11-07T13:02:10.909Z",
    "birthdate": "1983-12-08",
    "phone_number": "+49151000000012",
    "address": {
        "formatted": "Ballindamm 4\n22081\nHamburg\nDeutschland",
        "street_address": "Ballindamm 4",
        "locality": "Hamburg",
        "region": "",
        "country": "Deutschland",
        "postal_code": "22081",
        "address_line_2": "",
        "country_code": "DE",
        "company": ""
    }
}

Flows

Unidy supports three of the Open id connect flows. An excellent article that describes the different flows in detail can be found here: https://medium.com/@darutk/diagrams-of-all-the-openid-connect-flows-6968e3990660

In a nutshell, the different flows describe in which way the partner can access the user data after it has been granted access by the user. Which flow is used is determined by the response_type parameter. Possible values for this parameter are code, token, and id_token. Which flow should be used depends on the usecase. Unidy does not make any assumptions or enforce a specific flow.

Supported Flows

Additional optional parameters

See details for paramters here

Parameter	value
prompt	login, none see Silent Authorization
max_age	max elapsed time since last login
code_challenge	generated from code_verifier see PKCE Flow
code_challenge_method	plain, S256 see PKCE Flow
state	RECOMMENDED! secure random value
response_mode	form_post, fragment
login_hint	email address of the user to be prefilled

Auto approve

Unidy follows a default authorization process where users are required to grant permission for an application to access their data. This authorization phase includes a grant page. However, if you prefer to skip this screen, you have the option to configure the Oauth application to automatically approve the requested data.