Authorization with Webasyst ID

How to implement the authorization with Webasyst ID for server and client apps’ users

Contents...

The developers of websites and apps have the option of implementing authorization with Webasyst ID for their users, similar to the way one signs in via a social network account. The authorization procedure is based on oAuth 2.0 protocol.

Authorization options:

Authorization for server apps

The procedure is based on specification oAuth 2.0 / Authorization Code.

Steps of work:

  1. Obtain an authorization token.
  2. Send requests to Webasyst resource server.

Step 1. Obtaining an authorization token

  1. A server app; e.g., the server-side code of a website, redirects a user via a browser to Webasyst authorization server’s URL https://www.webasyst.com/id/oauth2/auth/code with the following GET parameters:
    • response_type=code. This is a required fixed parameter declaring that “Authorization Code” scheme is used.
    • client_id: the client ID, which must be obtained by the developer for their server app or website in Webasyst Customer Center.
    • scope: the list of permission identifiers, which are required for sending various requests to the Webasyst resource server. The identifiers must separated by the “+” character.

      Example: profile+license:read

      The list of available permission identifiers:
      • profile means access to the personal data of a Customer Center user, including the full name, email address, and uploaded photo. This permission is always requested by default, even if not specified explicitly.
      • license:read means access to the information about Webasyst software licenses owned by an authorized user.
      Read more about the use of various permissions in the descriptions of Webasyst resource server API methods.
    • redirect_uri: URL to which a user must be redirected after an authorization.
    • state: a randomly generated string of an arbitrary length.
  2. Webasyst authorization server offers a user to sign in, if a user is not authorized.
  3. Webasyst authorization server offers a user to confirm access for the server app to the data specified in scope parameter.
  4. Upon the user consent, Webasyst authorization server redirects the user to the URL which was specified in redirect_uri parameter. The following GET parameters are added to that URL:
    • code: a one-time authorization code with a short expiration period,
    • state: the string which was sent in state parameter.
  5. The server app verifies that the received GET parameter state matches that sent to Webasyst authorization server.
  6. The server app, without the use of a browser, sends a POST request to URL https://www.webasyst.com/id/oauth2/auth/token with the following values:
    • grant_type=authorization_code. This is a required fixed parameter.
    • code: the authorization code received from Webasyst authorization server.
    • redirect_uri: URL which was sent in redirect_uri parameter.
    • client_id: client ID which was sent in client_id parameter.
    • client_secret: a client secret, which must be obtained by the developer in Webasyst Customer Center for the server app or website.
  7. Webasyst authorization server returns a response in JSON format with the following contents: 
    {
    "access_token":"...",      //authorization token
    "token_type":"bearer",     //token type
    "expires_in":3600,         //token expiration period in seconds
    "refresh_token":"..."      //refresh token used to refresh the authorization token after it expires
}
    As of this moment, a user is considered as authorized.

    The obtained authorization token must be used to send requests to Webasyst resource server API to receive user-related data or to manage user assets.

Refreshing an authorization token

An authorization token must be refreshed once it expires otherwise Webasyst resource server will discontinue to process requests sent to its API. To refresh an authorization token means to obtain a new token by using the latest received refresh token.

To obtain a new authorization token, the server app must send a POST request to URL https://www.webasyst.com/id/oauth2/auth/token with the following values:

  • grant_type=refresh_token. This is a required fixed parameter, which denotes that refreshing of an authorization token is requested.
  • refresh_token: latest received refresh token.
  • client_id: client ID obtained in the Customer Center.
  • client_secret: a client secret, which must be obtained by the developer in Webasyst Customer Center for the server app or website.

Webasyst authorization server will return a response in the following format: 

{
    "access_token":"...",    //new authorization token
    "token_type":"bearer",   //token type
    "expires_in":3600,       //token expiration period in seconds
    "refresh_token":"..."    //new refresh token
}

Step 2. Sending requests to Webasyst resource server API

Obtained authorization token must be used to send requests to Webasyst resource server within the permissions confirmed by a user. Such requests can be used to obtain information about a user or to manage user assets.

Use the latest received token before it has expired. An expired authorization token must be refreshed to send further request to the API.

An authorization token must be sent within an HTTP header as shown below: 

Authorization: Bearer authorization_token

Webasyst resource server API returns response in JSON format.

Webasyst resource server API methods

Obtaining of personal data of a Webasyst Customer Center user

Required permissions: profile. 

GET: https://www.webasyst.com/id/api/v1/profile/

Response format: 

{
    "name":"Firstname Middlename Lastname",
    "firstname":"Firstname",
    "lastname":"Lastname",
    "middlename":"Middlename",
    "userpic":"https://{absolute URL of an uploaded user photo, 96x96 pixels large}",
    "userpic_original_crop":"https://{absolute URL of an uploaded user photo of original size}",
    "userpic_uploaded":{true or false},    //whether a user has an uploaded photo
    "email":[    //array of email addresses
        {
            "value":"name@domain.com",              //email address
            "ext":"work",                           //optional address type extension
            "status":{"confirmed" or "unknown"}     //address status
        },
        {
            "value":"...",
            "ext":"...",
            "status":"..."
        }
    ]
}
Obtaining of the list of framework installations where a user has enabled sign-in with Webasyst ID

Required permissions: profile. 

GET: https://www.webasyst.com/id/api/v1/installations/

Response format: 

[
    {
        "id":"{client_id of a framework installation}",
        "domain":"{domain name of an installation}",
        "url":"{absolute URL of an installation}"
    },
    {
        ...
    }
]
Obtaining of the list of software licenses owned by a user

Required permissions: license:read. 

GET: https://www.webasyst.com/id/api/v1/licenses/

Response format: 

[
    {
        "license_id":"{license identifier}",
        "slug":"{string ID of software product}",
        "product_id":"{numeric ID of software product}",
        "order_id":"{order number associated with purchased license}",
        "app_id":"{string ID of an app related to software product}",
        "ext_id":"{own ID of a plugin, design theme, or widget}",
        "type":"{type of software product — APP, PLUGIN, THEME, or WIDGET}",
        "name":"{name of software product}",
        "expire_date":{expiration date of software product’s hosted license, if applicable},
        "bound_to":"{domain name of a framework installation associated with the license}",
        "bind_available_date":{nearest available date when the license can be linked to another framework installation, if such linking is currently locked}
    },
    ...
 ]
Canceling of previously granted permissions to send requests about an authorized user

A user, once authorized via a server app, can cancel granted permissions in Webasyst Customer Center. This API method performs the same action. 

DELETE: https://www.webasyst.com/id/api/v1/delete/

Response format: 

{
    "delete":true
}

Authorization for client apps

Steps of work:

  1. Obtain an authorization token.
  2. Obtain the list of framework installations where a user has enabled sign-in with Webasyst ID.
  3. Obtain access codes for framework installations selected by a user.
  4. Obtain access tokens for selected framework installations’ API.
  5. Send API requests to framework installations’ apps.

API requests to framework installations is currently not supported for SPA. For this type of apps, only user authorization (step 1) and calling of Webasyst resource server API methods are available.

Step 1. Obtaining an authorization token

Procedure is based on specification oAuth 2.0 / Authorization Code + PKCE.

  1. A client app opens in a browser Webasyst authorization server’s URL https://www.webasyst.com/id/oauth2/auth/code with the following GET parameters:
    • response_type=code. This is a required fixed parameter declaring that “Authorization Code” scheme is used.
    • client_id: the client ID, which must be obtained by the developer for a client app in Webasyst Customer Center.
    • scope: string of the form token:{dot-separated string identifiers of Webasyst apps to which a client app must gain access when connected to a framework installation}.

      Example: token:shop.site.blog
      In this example, a client app attempts to gain access to Webasyst apps Shop-Script, Site, and Blog.
    • redirect_uri: URL to which a user must be redirected after an authorization.
    • state: a randomly generated string of an arbitrary length.
    • code_challenge: a hash of a one-time password generated before the sending of this request if the user device supports SHA256 hashing algorithm, or the password itself if SHA256 is not supported.
    • code_challenge_method: the hash generation method used for parameter code_challenge: "SHA256" if supported by user device or "plain" if SHA256 is not supported.

      A one-time password generated for the code_challenge parameter must be 43 to 128 characters long and may contain Latin letters and 4 special characters -._~ (hyphen, dot, underscore, and tilde).

      A hash must be generated by means of SHA256 algorithm if it is supported by user device. The generated hash must then be transformed into BASE64-URL-encoded format.

      If a user device does not support SHA256 algorithm then the generated password itself, without encryption, must be sent in code_challenge parameter.
  2. Webasyst authorization server offers a user to sign in, if a user is not authorized.
  3. Webasyst authorization server offers a user to confirm access for the client app to the data specified in scope parameter.
  4. Upon user consent, Webasyst authorization server redirects a user to the URL which was specified in redirect_uri parameter of the GET request. The following GET parameters are added to that URL:
    • code: a one-time authorization code with a short expiration period,
    • state: the string which was sent in the state parameter.
  5. The client app verifies that the value of received GET parameter state matches that sent to Webasyst authorization server.
  6. The client app, without the use of a browser, sends a POST request to URL https://www.webasyst.com/id/oauth2/auth/token with the following values:
    • grant_type=authorization_code. This is a required fixed parameter.
    • code: authorization code received from Webasyst authorization server.
    • redirect_uri: URL which was sent in redirect_uri parameter.
    • client_id: client ID which was sent in client_id parameter.
    • code_verifier: one-time password created for the generation of a hash in parameter code_challenge.
  7. Webasyst authorization server returns a response in the following format:

    {
    "access_token":"...",      //authorization token
    "token_type":"bearer",     //token type
    "expires_in":3600,         //token expiration period in seconds
    "refresh_token":"..."      //refresh token used to refresh the authorization token after it expires
}

The obtained authorization token must be used to call Webasyst resource server API methods. For example, the client app may request a user’s name and email address from their Customer Center profile or the list of framework installations in which a user has enabled sign-in with Webasyst, as described below in step 2.

Refreshing an authorization token

An authorization token used in a client app must be refreshed as described for server apps but without sending the client_secret parameter.

Step 2. Obtaining the list of framework installations with enabled sign-in with Webasyst ID

The client app sends a request to obtain the list of framework installations where a user has enabled sign-in with Webasyst ID.

Upon receipt of the installation list, the client app offers a user to select those to whose API the client app will send requests on behalf of an authorized user.

Step 3. Obtaining access codes for selected framework installations

The client app sends a POST request to URL https://www.webasyst.com/id/api/v1/auth/client/ with the following values: 

client_id[]=...&client_id[]=...&client_id[]=...

Alternatively, a client app may send data in JSON format within a POST request: 

{"client_id": ["...", "...", "..."]}

Webasyst authorization server will return access codes for selected framework installations in the following format: 

{
    "{client_id of a framework installation}":"{access code}",
    "{client_id of a framework installation}":"{access code}",
    ...
}

Step 4. Obtaining access tokens for selected framework installations’ API

To be able to call API methods of Webasyst apps in selected framework installations, the client app must obtain an API access token for each installation.

To do so, the client app must send POST requests to those installations’ URLs {root installation URL}/api.php/token-headless with the following values:

  • code: access code received from Webasyst authorization server for a specific framework installation.
  • scope: dot-separated list of Webasyst app IDs access to which is required for the client app’s functioning. Specified app IDs must match those sent in step 1 for the obtaining of an authorization token.

    Example: shop.site.blog
  • client_id: arbitrary unique app identifier created at the developer’s discretion. For web apps, it is recommended to add a part of a domain name to the identifier to avoid eventual conflicts.

    Example: XYZCompanyShopImportApp

The API of a framework installation will respond to such a request by returning an access token in the following format: 

{
    "access_token":"..." //access token
}

Step 5. Sending API requests to framework installations’ apps

The obtained access token must be used in the client app to call API methods of the apps whose IDs were specified in scope parameter.