Client registration

Client applications must be registered with an OAuth 2.0 authorisation server before they can receive tokens from it.

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

• OAuth 2.0 Dynamic Client Registration Protocol (RFC 7591) – defines a protocol and metadata for registering a client;
• OAuth 2.0 Dynamic Client Registration Management Protocol (RFC 7592) – defines GET, UPDATE and DELETE operations for reading and 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 OAuth 2.0 client

Example request to register a client 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.*;

// 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
ClientMetadata clientMetadata = new ClientMetadata();
clientMetadata.setGrantTypes(Collections.singleton(GrantType.AUTHORIZATION_CODE));
clientMetadata.setRedirectionURI(URI.create("https://example.com/cb"));
clientMetadata.setName("My Client App");

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

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

ClientRegistrationResponse regResponse = ClientRegistrationResponse.parse(httpResponse);

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

// Successful registration
ClientInformationResponse successResponse = (ClientInformationResponse)regResponse;
ClientInformation clientInfo = successResponse.getClientInformation();

// 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 client’s registration

The details of a registered relying party can be read at the URL for its 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 = ClientRegistrationResponse.parse(httpResponse);

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

// Success
successResponse = (ClientInformationResponse)regResponse;

// Print the client registration data
System.out.println(successResponse.getClientInformation().toJSONObject());

Updating a relying party’s registration

A client may be allowed to updated its registration. Here is an example request to update the client name, which the OAuth 2.0 authorisation server typically displays to end-users during consent:

// Update client name
clientMetadata = clientInfo.getMetadata();
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 = ClientRegistrationResponse.parse(httpResponse);

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

// Success
successResponse = (ClientInformationResponse)regResponse;

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

Deleting a client’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