OAuth 2.0 Client registration

Client applications must be registered with an OAuth 2.0 server before they can send authorisation requests to it.

The OAuth WG has devised a RESTful API to facilitate registration of clients and the subsequent management of their data:

Depending on the OAuth 2.0 server policy, access to the registration endpoint can be open, require pre-approval, or it may even be hidden behind some developer portal. The Connect2id server requires a master API token to register clients, unless some other 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());

Querying a client's registration

Once the client is registered, its details can always be queried at the URL for its resource, e.g. https://demo.c2id.com/c2id/clients/b5noxshmay5xw, using the provisioned 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 client's registration

The details of the client registration can also be updated. Here is an example request to update the name of the client that the OAuth 2.0 server displays to the end-user 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