Datasource Connections

Once a Wallet account is created, a Data Source must be connected to perform the role of a resource server and/or an identity provider. In the role of a resource server, a Data Source stores data that belongs to the user. The Wallet can use the stored data, such as the user's profile information, to help the user log in, and in turn, perform the role of an identity provider.

The process to connect a Data Source as an identity provider occurs in the account creation flow, connecting a Data Source as a resource server, on the other hand, can be done through the Data Source connection flow.

Data Source Connection - Overview

The Data Source connection process starts with an authorization request from the client to the Wallet Server. Similarly to the Account Creation Flow, the client receives a response with an authorization request URL, a session key, and a pending authorization request ID.

The client redirects to the user agent where an authorization request is sent to the Data Source, initiating an authorization process. The Wallet Server then receives a callback. Next, the Wallet Server redirects back to the client, where the client has to provide the pending_auth_request_id to acquire the Data Source account ID.

As the last step of the process, a Data Source Account is created and the Data Source Account ID is sent to the Wallet Client.

Sequence Diagram: Figure: Create DSA

Data Source Connection - Process Flow

note

Before starting a data source connection process, ensure the Wallet Server is appropriately configured. Refer to the Wallet Server application configuration for details to configure the following properties:

navigator.redirects.baseUrl
navigator.useIntermediateCallbackUI

Get Data Source Authorization Endpoint

Step 1 in the sequence diagram

When the Wallet Client has determined which datasource_id to use, it must send the following request to the Wallet Server to get the authorization endpoint for the Data Source:

Sample Request

curl -X POST \
  '{{WS_BASE_URI}}/data-sources/{datasource_id}/requests' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{WALLET_SESSION_TOKEN}}'

Note that this is an authenticated request, and a valid Wallet Session token must be included as a Bearer token in the Authorization header of the request, as shown. See the Account and Session Management section for more information on how to obtain a Wallet Session.

The Wallet Server responds to this request with an auth_request URL, session_key, and a pending_auth_request_id. These values will be used in subsequent steps to obtain a Data Source Account ID.

Sample Response

{
  "auth_request": "http://www.example.com/authorize?callback_uri=x&state=y&client_id=xx&response_type=code",
  "session_key": "string",
  "pending_auth_request_id": "string"
}

Perform Data Source Authorization

Steps 3-6 in the sequence diagram

The client can initiate the Authorization process at the Data Source by following the auth_request URL.

Once the authorization process at the Data Source is completed, the user agent is redirected to the Wallet Server's Data Source callback endpoint. If the Wallet Server's setting for navigator.useIntermediateCallbackUI is set to true, the User Agent will be shown a page confirming successful authorization and containing a button to return to the client application. If it's set to false, the User Agent will be redirected directly back to the client application.

The Wallet Server will make this callback to the client application according to the value of the navigator.redirects.dsPath configuration property. The Wallet Client must expose this endpoint in order to receive the callback.

The Wallet Server will construct the callback URL by adding the Data Source ID of the connected Data Source as a query parameter. The Wallet Server makes the callback as a 302 response to the user agent. The user agent will then follow the redirect to the URL provided in the response location header by making a GET request:

Sample Callback

curl -X GET '{{WALLET_CLIENT_URI}}/rs-callback?datasource=3'

Get a Data Source Account ID

Step 7 in the sequence diagram

After receiving the callback shown above, the Wallet Client may now make a request to obtain a Data Source Account ID. The value for pending_auth_request_id that was obtained previously must be included in the following request:

Sample Request

curl -X GET \
  '{{WS_BASE_URI}}/data-sources/{datasource_id}/requests/{request_id}' \
  --header 'Authorization: Bearer {{WALLET_SESSION_TOKEN}}'

In response, the Wallet Server provides a Data Source Account (DSA) ID to the Client, confirming a Data Source connection has been successfully completed.

Sample Response

{
  "ds_account_id": "string",
  "sub": "string",
  "nickname": "string",
  "rot": {
    "expires_at": "2023-02-15T16:46:13.922Z"
  },
  "disabled": "2023-02-15T16:46:13.922Z",
  "connected_on": "2023-02-15T16:46:13.922Z",
  "authenticator": true,
  "last_active": "2023-02-15T16:46:13.922Z",
  "datasource": {
    "data_source_id": "string",
    "required": true,
    "style": {
      "style_color": "string",
      "style_font_color": "string",
      "logo_url": "string"
    },
    "name": "string",
    "organization": {
      "id": "string",
      "name": "string"
    },
    "resources": [
      {
        "rs_res_id": "string",
        "resource": {
          "authorization_server_id": "string",
          "type": "string",
          "name": "string",
          "res_def_id": "string",
          "scopes": [
            "string"
          ],
          "named_scopes": [
            {
              "manage_url": "string",
              "verified_sources": [
                {
                  "name": "string",
                  "logo_url": "string"
                }
              ]
            }
          ]
        },
        "approved_scopes": [
          "string"
        ],
        "named_approved_scopes": [
          {
            "manage_url": "string",
            "verified_sources": [
              {
                "name": "string",
                "logo_url": "string"
              }
            ]
          }
        ]
      }
    ]
  },
  "account_resources": [
    {
      "identifier": "smile-cdr-profile-id",
      "type": "http://google.com",
      "location": "http://127.0.0.1:8086",
      "description": "all-enrolled-resources-self",
      "name": "resource-name",
      "as_uri": "http://127.0.0.1:8081",
      "content_types_supported": "application/json",
      "scopes": [
        "fpx_rot"
      ]
    }
  ],
  "error": "string"
}

Manage Data Source Account

Get List of Data Source Accounts

Get all the data source accounts connected to an authenticated user

Sample Request

curl -X GET \
  '{{WS_BASE_URI}}/me/ds-accounts' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{WALLET_SESSION_TOKEN}}'

Sample Response

[
  {
    "ds_account_id": "string",
    "sub": "string",
    "nickname": "string",
    "rot": {
      "expires_at": "2022-12-08T19:02:53.050Z"
    },
    "disabled": "2022-12-08T19:02:53.050Z",
    "connected_on": "2022-12-08T19:02:53.050Z",
    "authenticator": true,
    "last_active": "2022-12-08T19:02:53.050Z",
    "datasource": {
      "data_source_id": "string",
      "required": true,
      "style": {
        "style_color": "string",
        "style_font_color": "string",
        "logo_url": "string"
      },
      "name": "string",
      "organization": {
        "id": "string",
        "name": "string"
      },
      "resources": [
        {
          "rs_res_id": "string",
          "resource": {
            "authorization_server_id": "string",
            "type": "string",
            "name": "string",
            "res_def_id": "string",
            "scopes": [
              "string"
            ],
            "named_scopes": [
              {
                "manage_url": "string",
                "verified_sources": [
                  {
                    "name": "string",
                    "logo_url": "string"
                  }
                ]
              }
            ]
          },
          "approved_scopes": [
            "string"
          ],
          "named_approved_scopes": [
            {
              "manage_url": "string",
              "verified_sources": [
                {
                  "name": "string",
                  "logo_url": "string"
                }
              ]
            }
          ]
        }
      ]
    },
    "account_resources": [
      {
        "identifier": "smile-cdr-profile-id",
        "type": "http://google.com",
        "location": "http://127.0.0.1:8086",
        "description": "all-enrolled-resources-self",
        "name": "resource-name",
        "as_uri": "http://127.0.0.1:8081",
        "content_types_supported": "application/json",
        "scopes": [
          "fpx_rot"
        ]
      }
    ]
  }
]

Get Details on a Data Source Account

Get information on a specific data source account

Sample Request

curl -X GET \
  '{{WS_BASE_URI}}/me/ds-accounts/{DataSourceAccountID}' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{WALLET_SESSION_TOKEN}}'

Sample Response

{
  "ds_account_id": "string",
  "sub": "string",
  "nickname": "string",
  "rot": {
    "expires_at": "2022-12-08T19:04:19.155Z"
  },
  "disabled": "2022-12-08T19:04:19.155Z",
  "connected_on": "2022-12-08T19:04:19.155Z",
  "authenticator": true,
  "last_active": "2022-12-08T19:04:19.155Z",
  "datasource": {
    "data_source_id": "string",
    "required": true,
    "style": {
      "style_color": "string",
      "style_font_color": "string",
      "logo_url": "string"
    },
    "name": "string",
    "organization": {
      "id": "string",
      "name": "string"
    },
    "resources": [
      {
        "rs_res_id": "string",
        "resource": {
          "authorization_server_id": "string",
          "type": "string",
          "name": "string",
          "res_def_id": "string",
          "scopes": [
            "string"
          ],
          "named_scopes": [
            {
              "manage_url": "string",
              "verified_sources": [
                {
                  "name": "string",
                  "logo_url": "string"
                }
              ]
            }
          ]
        },
        "approved_scopes": [
          "string"
        ],
        "named_approved_scopes": [
          {
            "manage_url": "string",
            "verified_sources": [
              {
                "name": "string",
                "logo_url": "string"
              }
            ]
          }
        ]
      }
    ]
  },
  "account_resources": [
    {
      "identifier": "smile-cdr-profile-id",
      "type": "http://google.com",
      "location": "http://127.0.0.1:8086",
      "description": "all-enrolled-resources-self",
      "name": "resource-name",
      "as_uri": "http://127.0.0.1:8081",
      "content_types_supported": "application/json",
      "scopes": [
        "fpx_rot"
      ]
    }
  ]
}

Update Nickname

This call enables a user to set a data source account name according to their preference. For example, Bob's Data Source.

Sample Request

curl -X POST \
  '{{WS_BASE_URI}}/me/ds-accounts/{DataSourceAccountID}/nickname' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{WALLET_SESSION_TOKEN}}'

Sample Response

{
  "ds_account_id": "string",
  "sub": "string",
  "nickname": "string",
  "rot": {
    "expires_at": "2022-12-08T19:05:30.154Z"
  },
  "disabled": "2022-12-08T19:05:30.154Z",
  "connected_on": "2022-12-08T19:05:30.154Z",
  "authenticator": true,
  "last_active": "2022-12-08T19:05:30.154Z",
  "datasource": {
    "data_source_id": "string",
    "required": true,
    "style": {
      "style_color": "string",
      "style_font_color": "string",
      "logo_url": "string"
    },
    "name": "string",
    "organization": {
      "id": "string",
      "name": "string"
    },
    "resources": [
      {
        "rs_res_id": "string",
        "resource": {
          "authorization_server_id": "string",
          "type": "string",
          "name": "string",
          "res_def_id": "string",
          "scopes": [
            "string"
          ],
          "named_scopes": [
            {
              "manage_url": "string",
              "verified_sources": [
                {
                  "name": "string",
                  "logo_url": "string"
                }
              ]
            }
          ]
        },
        "approved_scopes": [
          "string"
        ],
        "named_approved_scopes": [
          {
            "manage_url": "string",
            "verified_sources": [
              {
                "name": "string",
                "logo_url": "string"
              }
            ]
          }
        ]
      }
    ]
  },
  "account_resources": [
    {
      "identifier": "smile-cdr-profile-id",
      "type": "http://google.com",
      "location": "http://127.0.0.1:8086",
      "description": "all-enrolled-resources-self",
      "name": "resource-name",
      "as_uri": "http://127.0.0.1:8081",
      "content_types_supported": "application/json",
      "scopes": [
        "fpx_rot"
      ]
    }
  ]
}

Disable Account

Disable a data source account

Sample Request

curl -X POST \
  '{{WS_BASE_URI}}/me/ds-accounts/{DataSourceAccountID}/disable' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer {{WALLET_SESSION_TOKEN}}'

Sample Response

{
  "ds_account_id": "string",
  "sub": "string",
  "nickname": "string",
  "rot": {
    "expires_at": "2022-12-08T19:08:07.608Z"
  },
  "disabled": "2022-12-08T19:08:07.608Z",
  "connected_on": "2022-12-08T19:08:07.608Z",
  "authenticator": true,
  "last_active": "2022-12-08T19:08:07.608Z",
  "datasource": {
    "data_source_id": "string",
    "required": true,
    "style": {
      "style_color": "string",
      "style_font_color": "string",
      "logo_url": "string"
    },
    "name": "string",
    "organization": {
      "id": "string",
      "name": "string"
    },
    "resources": [
      {
        "rs_res_id": "string",
        "resource": {
          "authorization_server_id": "string",
          "type": "string",
          "name": "string",
          "res_def_id": "string",
          "scopes": [
            "string"
          ],
          "named_scopes": [
            {
              "manage_url": "string",
              "verified_sources": [
                {
                  "name": "string",
                  "logo_url": "string"
                }
              ]
            }
          ]
        },
        "approved_scopes": [
          "string"
        ],
        "named_approved_scopes": [
          {
            "manage_url": "string",
            "verified_sources": [
              {
                "name": "string",
                "logo_url": "string"
              }
            ]
          }
        ]
      }
    ]
  },
  "account_resources": [
    {
      "identifier": "smile-cdr-profile-id",
      "type": "http://google.com",
      "location": "http://127.0.0.1:8086",
      "description": "all-enrolled-resources-self",
      "name": "resource-name",
      "as_uri": "http://127.0.0.1:8081",
      "content_types_supported": "application/json",
      "scopes": [
        "fpx_rot"
      ]
    }
  ]
}

Data Source Connection - Overview​

Data Source Connection - Process Flow​

Get Data Source Authorization Endpoint​

Sample Request​

Sample Response​

Perform Data Source Authorization​

Sample Callback​

Get a Data Source Account ID​

Sample Request​

Sample Response​

Manage Data Source Account​

Get List of Data Source Accounts​

Sample Request​

Sample Response​

Get Details on a Data Source Account​

Sample Request​

Sample Response​

Update Nickname​

Sample Request​

Sample Response​

Disable Account​

Sample Request​

Sample Response​

Data Source Connection - Overview

Data Source Connection - Process Flow

Get Data Source Authorization Endpoint

Sample Request

Sample Response

Perform Data Source Authorization

Sample Callback

Get a Data Source Account ID

Sample Request

Sample Response

Manage Data Source Account

Get List of Data Source Accounts

Sample Request

Sample Response

Get Details on a Data Source Account

Sample Request

Sample Response

Update Nickname

Sample Request

Sample Response

Disable Account

Sample Request

Sample Response