Using device authorization with Code Sign Manager clients

Device authorization lets a user on a signing workstation authenticate to Trust Protection Foundation through a web browser instead of entering credentials at the command line. When you request a grant using device authorization, the client obtains a verification URL from the authentication server and opens it in your default web browser. You sign in there, and the client completes the grant automatically.

This method is useful when your organization authenticates users through a SCIM identity provider, because the sign-in happens in the browser against that provider rather than in the terminal.

Prerequisites

• The SCIM Identity connector is configured in Trust Protection Foundation Configuration Console.

• Your Trust Protection Foundation server is at version 26.1 or later.

• Device authorization is enabled in Trust Protection Foundation Configuration Console. An administrator enables it from the Access Management node: click Change Global Settings, select the Device tab, and turn on the Enabled setting.

• The Code Sign Manager client is installed on the signing workstation, and the person using the private keys has Key User permission on at least one project.

• A default web browser is available on the signing workstation.

  If a browser isn't available on the signing workstation, you can still complete the flow manually using a browser on any machine. See If the browser doesn't open automatically.

Getting a grant using device authorization

Run the getgrant command with the --device option, using the configuration utility for your client (cspconfig, pkcs11config, gpgconfig, or tkdriverconfig).

$ pkcs11config getgrant --device

Opening your default browser for device authorization...
Use the key user's name and password.
If the browser does not open automatically, use the verification URL below:
Verification URL: https://TPP_SERVER_URL/aperture/activate/03F5-0DCA

When you run this command, the following happens:

1. The client requests device authorization from the authentication server and receives a verification URL.

2. The client validates the verification URL before using it. If the URL fails validation, the client stops the flow rather than opening the browser. See Troubleshooting device authorization.

3. The client opens the verification URL in your default web browser. The URL is also printed in the terminal.

4. In the browser, sign in using the key user's name and password.

5. While you sign in, the client polls the authentication server and reports that the request is still pending. After you finish signing in, the client obtains the grant and stores it.

While the client is waiting, it displays the following message at each polling interval:

The authorization request is still pending as the end user hasn't yet completed the user-interaction steps

If the browser doesn't open automatically

If the client cannot open a browser, the device authorization flow continues normally. The client prints the verification URL so that you can open it yourself.

$ pkcs11config login --device

Please complete device authorization in your web browser using the verification URL below.
Use the key user's name and password.
Verification URL: https://TPP_SERVER_URL/aperture/activate/03F5-0DCA

Copy the verification URL into a browser on any machine, sign in with the key user's name and password, and the client completes the grant as usual.

Polling and timeout behavior

After the verification URL is issued, the client polls the authentication server until you complete the sign-in. The following limits apply:

• The client polls at the interval requested by the server, with a minimum of 5 seconds.

• The polling interval is capped at 15 minutes. If the server requests a longer interval, the client caps it.

• The client stops after 120 polling attempts, which is approximately 10 minutes at the minimum interval.

If you don't complete the sign-in before the client stops polling, the client reports a timeout.

Run the getgrant --device command again to start a new device authorization request.

Troubleshooting device authorization