SSI OAuth
OAuth (Open Authorization) is a protocol or set of rules used for token-based Internet authorization. It enables third-party systems to use end-user account information without exposing the user's credentials. Acting as a mediator, OAuth allows a third-party system to obtain an access token that authorizes the exchange of certain account information.
SSI OAuth is an authorization method based on the OAuth 2.0 protocol, enriched by the advantages of using Self-Sovereign Identity (SSI).
By leveraging Verifiable Credentials and Zero-Knowledge Proofs within OAuth, both the quantity of data available for authorization and the level of privacy are enhanced simultaneously. Including additional data from verifiable credentials improves the accuracy and effectiveness of authorization rules. Zero Knowledge Proofs enable the verification of specific claims or attributes without the need to disclose unnecessary or sensitive information. By combining verifiable credentials data and Zero-Knowledge Proofs, organizations can strike a balance between obtaining comprehensive information for authorization purposes and preserving individuals' privacy. This approach empowers organizations to make informed decisions based on a comprehensive data set while upholding individuals' privacy rights.
SSI OAuth uses a client's credentials that have been set as required to complete an interaction that allows or denies a client access to a third-party service.
ProofSpace supports the OAuth 2.0 authorization framework described in RFC 6749, as well as its extension described in RFC 8628.
RFC 6749 - "The OAuth 2.0 Authorization Framework," is the core specification for the OAuth 2.0 protocol. It defines the framework for obtaining access tokens, which are used to grant access to protected resources in a secure and standardized way.
RFC 8628 - "OAuth 2.0 Device Authorization Grant" or "Device Flow" is an extension to OAuth 2.0. It introduces a grant type that allows devices with limited input capabilities (e.g., smart TVs, Internet of Things (IoT) devices) to request authorization from users.
The Device Authorization Grant enables devices to display a verification code or URL to the user, who can then enter this code or visit the URL on a separate device (e.g., a smartphone or computer) to complete the authorization process. This flow is useful when devices cannot directly interact with complex authentication flows, such as those involving username and password inputs.
In addition to the implementation features of the protocols, RFC6749 requires more integration efforts on your backend. Click here to find an example of how to implement the Authorization described in RFC 6749.
The RFC 8628 is more frontend-oriented, and ProofSpace provides a TypeScript library to facilitate the implementation.
For further details and setup information about the OAuth extension, please refer to the table below.
Features | Description | Screenshots |
|---|---|---|
Install Extension
| To use the SSI OAuth in your interaction, you need to install the "OAuth" extension to your service. Make sure you have the JWT key pair ready before installing this extension.
Go to the “Extensions“ tab and click “Install Extension.“ |
|
| On the next page, select "Public Extensions," and then click "Install" on the "OAuth" extension’s field. |
|
Add JWT key | In the pop-up window, select the key type and enter the private and public keys in the appropriate fields. These keys will be used to sign the JWT token that will be passed to the end user. After that, Click “Submit.“ After completing the installation process, you can now navigate to the "Interactions" tab and add this extension to the desired interaction. |
|
Add “Oauth” extension to the interaction | On the “Interactions“ tab, click “Edit“ button for the chosen interaction. in the “Edit Interaction“ page, click “Select“ on the “Extension Setup“ section. |
|
| In the Extension Settings pop-up window, click “Add” next to the OAuth extension. |
|
Add details to your extension | In the "Extension Settings" pop-up, enter the "Client Secret" (required) and any additional configuration settings you need. | |
clientId | The “clientId“ field is “Read only.” The client ID will be generated automatically after you click “Submit.“ |
|
clientSecret | Add the “clientSecret.“ This is the only required field in this configuration. |
|
redirectUris | If you wish to restrict redirect URIs where the end-user will be redirected in case of the successful authorisation, add redirect URIs here. If you leave this field empty, the end-user will be redirected to any URI received in the authorisation request. |
|
scopes | Specify the user scopes with different access levels in this section. |
|
jwtFields | By default, JWT token will contain two fields - “subscriberConnectDID and “publicServiceDID.“ In this field, you can configure additional fields that will be included in the JWT Token. To do this, assign a name to each additional field and select the source of data for that field, which can be either the input request or a specific credential. If you choose to use a credential as the data source, provide the credential ID and the corresponding field name of this credential from which you wish to retrieve the data. |
|
scopeFields | In this section, you can set up access to the restricted resource, based on specific user credential data for different scopes of users, which are specified in the "scopes" field . Enter the name of chosen scope. Enter credential ID, field name of this credential and set rules for the chosen access level in the “fieldOperator“ (<,>,=,<=,>=) and “fieldValue“ fields. For example, if you want to grant editing rights to users that has an “Access Level” greater than “4” in the "Scope" credential, you can configure it as follows:
Then, after saving these configurations, add the “Scope“ credential to the “Required Credential Definitions” section of the authorization interaction. With this configuration, in order to grant the user editing rights to the restricted resource, the authorization interaction will require the user to share the value of the "Access Level" attribute from their ID wallet's "Scope" credential. This value will have to be greater than 4 for the user to be granted the editing rights. |
|
ExpirationTime
| To set the expiration time of the tokens and QR code used in this authorization, enter the desired length of time (in seconds) in the appropriate fields. Please note that if you add the “OAuth” extension to the interaction, you will not be able to set the dynamic QR code as the initiation media for this interaction. The OAuth extension and dynamic QR code initiation media cannot be used together in the same interaction. |
|
| After adding all the settings, click "Submit." The “SSI Authentication 1.0” credential definition (credential, issued by the ProofSpace ID service) will be automatically added to the "Credentials required by extension" section of this interaction. | |
Save changes | After completing these steps, click "Done" to save all additional changes made to this interaction. |
|