Skip to content
Connect2id

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:

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

Was this helpful?

Rate limit reached. Try again after a minute.
Last updated:
Native SSO →