Relying party registration

Client applications (called relying parties) must be registered with an OpenID provider before they can authenticate users with it.

A standard RESTful API enables the registration of relying parties and the management of their data:

• OpenID Connect Dynamic Client Registration 1.0 – defines a protocol and metadata for registering and querying an OpenID Connect relying party;
• OAuth 2.0 Dynamic Client Registration Management Protocol (RFC 7592) – defines additional UPDATE and DELETE operations for managing an existing registration.

Depending on the OpenID Connect provider policy, access to the registration endpoint can be open, require authorisation, or may even be managed by a developer portal. The Connect2id server requires a master token to register clients, unless another access method is configured.

Registering a new OpenID relying party

Example request to register a relying party for the code grant (flow):

import com.nimbusds.oauth2.sdk.*;
import com.nimbusds.oauth2.sdk.client.*;
import com.nimbusds.oauth2.sdk.http.*;
import com.nimbusds.oauth2.sdk.token.*;
import com.nimbusds.openid.connect.rp.*;

// The client registration endpoint
URI clientsEndpoint = new URI("https://demo.c2id.com/c2id/clients");

// Master API token for the clients endpoint
BearerAccessToken masterToken = new BearerAccessToken("ztucZS1ZyFKgh0tUEruUtiSTXhnexmd6");

// We want to register a client for the code grant
OIDCClientMetadata clientMetadata = new OIDCClientMetadata();
clientMetadata.setGrantTypes(Collections.singleton(GrantType.AUTHORIZATION_CODE));
clientMetadata.setRedirectionURI(URI.create("https://example.com/cb"));
clientMetadata.setName("My Client App");

OIDCClientRegistrationRequest regRequest = new OIDCClientRegistrationRequest(
    clientsEndpoint,
    clientMetadata,
    masterToken
);

HTTPResponse httpResponse = regRequest.toHTTPRequest().send();

ClientRegistrationResponse regResponse = OIDCClientRegistrationResponseParser.parse(httpResponse);

if (! regResponse.indicatesSuccess()) {
    // We have an error
    ClientRegistrationErrorResponse errorResponse = (ClientRegistrationErrorResponse)regResponse;
    System.err.println(errorResponse.getErrorObject());
    return;
}

// Successful registration
OIDCClientInformationResponse successResponse = (OIDCClientInformationResponse)regResponse;
OIDCClientInformation clientInfo = successResponse.getOIDCClientInformation();

// The client credentials - store them:
// The client_id
System.out.println("Client ID: " + clientInfo.getID());
// The client_secret
System.out.println("Client secret: " + clientInfo.getSecret().getValue());
// The client's registration resource
System.out.println("Client registration URI: " + clientInfo.getRegistrationURI());
// The token for accessing the client's registration (for update, etc)
System.out.println("Client reg access token: " + clientInfo.getRegistrationAccessToken());

// Print the remaining client metadata
System.out.println("Client metadata: " + clientInfo.getMetadata().toJSONObject());

Reading a relying party’s registration

The details of a registered relying party can be read using its resource URL, e.g. https://demo.c2id.com/c2id/clients/b5noxshmay5xw. This requires the registration access token.

ClientReadRequest readRequest = new ClientReadRequest(
    clientInfo.getRegistrationURI(),
    clientInfo.getRegistrationAccessToken()
);

httpResponse = readRequest.toHTTPRequest().send();

regResponse = OIDCClientRegistrationResponseParser.parse(httpResponse);

if (! regResponse.indicatesSuccess()) {
    // We have an error
    ClientRegistrationErrorResponse errorResponse = (ClientRegistrationErrorResponse)regResponse;
    System.err.println(errorResponse.getErrorObject());
    return;
}

// Success
successResponse = (OIDCClientInformationResponse)regResponse;

System.out.println("Client registration data: " + successResponse.getClientInformation().toJSONObject());

Updating a relying party’s registration

A relying party may be allowed to update its registration. Here is an example request to update the relying party name, which the OpenID provider typically displayes to end-users during consent:

// Update client name
clientMetadata = clientInfo.getOIDCMetadata();
clientMetadata.setName("My app has a new name");

// Send request
ClientUpdateRequest updateRequest = new ClientUpdateRequest(
    clientInfo.getRegistrationURI(),
    clientInfo.getID(),
    clientInfo.getRegistrationAccessToken(),
    clientMetadata,
    clientInfo.getSecret()
);

httpResponse = updateRequest.toHTTPRequest().send();

regResponse = OIDCClientRegistrationResponseParser.parse(httpResponse);

if (! regResponse.indicatesSuccess()) {
    // We have an error
    ClientRegistrationErrorResponse errorResponse = (ClientRegistrationErrorResponse)regResponse;
    System.err.println(errorResponse.getErrorObject());
    return;
}

// Success
successResponse = (OIDCClientInformationResponse)regResponse;

// Ensure the client name has been updated
clientInfo = successResponse.getOIDCClientInformation();
System.out.println("Client name: " + clientInfo.getMetadata().getName());

Deleting a relying party’s registration

Finally, the client can request to have its registration deleted:

ClientDeleteRequest deleteRequest = new ClientDeleteRequest(
    clientInfo.getRegistrationURI(),
    clientInfo.getRegistrationAccessToken()
);

httpResponse = deleteRequest.toHTTPRequest().send();

if (! httpResponse.indicatesSuccess()) {
    // We have an error
    System.err.println(ClientRegistrationErrorResponse.parse(httpResponse).getErrorObject());
    return;
}

// Success: nothing returned