Application Registration#

Added in version 2.0.

By default, ESS’ Broker Service supports static registration of client applications. Using the Application Registration feature, users can statically register their applications to receive client credentials (i.e., Client ID and Client Secret). ESS’ application registration returns Client ID of type UUID. [1]

Warning

Safeguard your Client ID and Client Secret values. Do not share these with any third parties as anyone with your Client ID and Client Secret values can impersonate you and act fully on your behalf.

With these client credentials, your applications can perform authentication flow without the need for browser-based user interactions with the Identity Provider.

To Register#

Go to the Application Registration page; e.g., https://openid.<ESSDOMAIN>/registration.html.
If not already logged in, you will redirect to the login page. Log in with your username and password.
In the Register an app textbox, enter your application’s name and click Register.
The Client ID and Client Secret for your application appears under Apps You’ve Registered list.
Note
- You can register up to 10 applications.
- You can delete an application’s registration by clicking on the three-dot icon and selecting Delete app from the menu.

Authenticate with Client Credentials#

Once you have registered the application, you can use its client credentials in the application’s login code. Specifically, your application can perform Client Credentials flow.

Tip

To create an ACP policy that allows your registered client to access your Pod data, see Create Policy for Client Applications.

You can use the registered client credentials with Inrupt’s Java Client Library to create an authenticated session. Once you have the authenticated session, you can create a client for the session and perform authenticated operations:

/**
 * Note 1: OpenIdSession.ofClientCredentials
 * Using the client credentials, create an authenticated session.
 */

final Session session = OpenIdSession.ofClientCredentials(
        URI.create(System.getenv("MY_SOLID_IDP")).normalize(),
        System.getenv("MY_SOLID_CLIENT_ID"),
        System.getenv("MY_SOLID_CLIENT_SECRET"),
        "client_secret_basic");

/**
 * Note 2: SolidSyncClient
 * Instantiates a synchronous client for the authenticated session.
 * The client has methods to perform CRUD operations.
 */
final SolidSyncClient client = SolidSyncClient.getClient().session(session);

/**
 * Note 3: SolidSyncClient.read()
 * Using the SolidSyncClient client.read() method,
 * - Reads the RDF resource into the Expense class, which extends SolidRDFSource class
 */
final URI uri = URI.create(resourceURL).normalize();
try (Expense resource = client.read(uri, Expense.class)) {
   // Various Processing

} catch (NotFoundException e1) {

    // ...
} catch(ForbiddenException e2) {
    // ...
} catch(Exception e) {
   // ...
}

For more information on the Java Client Library, see:

You can use the registered client credentials to login with the @inrupt/solid-client-authn-node library. Once logged in, your application can perform authenticated operations:

const { Session } = require("@inrupt/solid-client-authn-node");
const { getSolidDataset } = require("@inrupt/solid-client");

const session = new Session();

// Call loginAndRead with your Client ID and Secret
function loginAndRead(myClientId, myClientSecret, myIDP) {
  try {
    // Log in using the credentials from the registered client.
    session
      .login({
        clientId: myClientId,
        clientSecret: myClientSecret,
        oidcIssuer: myIDP
      })
      .then(() => {
        if (session.info.isLoggedIn) {
          console.info("INFO::::::::: Logged In with Client Credentials.");

          // Perform some operation
          getMyData("<Your Resource URL to fetch>");
        }
      });
  } catch (err) {
    console.log(err);
  }
}

function getMyData(url) {
  getSolidDataset(url, { fetch: session.fetch })
    .then((response) => {
      // Various Processing
    });
}

You can use the client credentials to request an Access Token. Once you have the Access Token, you can then perform authenticated requests:

Find the token_endpoint for ESS.
1. Go to https://openid.<ESS DOMAIN>/.well-known/openid-configuration.
2. In the returned JSON document, find the token_endpoint value:
```
{
  ...
  "token_endpoint": <Your Token Endpoint Value>,
  ...
}
```

Post a request to this token_endpoint value with your client credentials:

def get_access_token(client_id, client_secret, token_endpoint, dpop):
    """

    :param client_id: Your Client ID
    :param client_secret: Your Client Secret
    :param token_endpoint: Your ESS OIDC Broker Token Endpoint
    :param dpop: DPoP value for Header
    :return: Access Token
    """
    response = requests.post(token_endpoint,
                             auth=(client_id, client_secret),
                             headers={'DPoP': dpop},
                             data={'grant_type': 'client_credentials'})

    return response.json()['access_token']

Use the access_token in accessing your Pod. For example, the following performs a GET request of a Resource for which you have access:

def get_data(url, access_token):
    """

    :param url: Resource URL to get
    :param access_token: Obtained from get_access_token
    :return:
    """
    headers = {"Authorization": "Bearer " + access_token}

    my_data = requests.get(url, headers=headers)
    print(my_data.text)

Configuration#

To disable the Register an Application feature, set INRUPT_OPENID_CATALOG_DISABLED to true.