AddPermissions Method

AddPermissions(PinUvAuthTokenPermissions, string?)

Obtain a PinUvAuthToken that possesses the given permissions along with the current permissions. This is generally called early in a session to specify which set of permissions you expect to need for the operations you will be calling.

C#

public void AddPermissions(PinUvAuthTokenPermissions permissions, string? relyingPartyId = null)

Parameters

Type	Name	Description
PinUvAuthTokenPermissions	permissions	An OR of all the permissions you expect to be needed during the session.
string	relyingPartyId	If needed or wanted, how to specify the relying party in question. The default for this parameter is null, so if no arg is given, then there will be no relying party specified.

Exceptions

Type	Condition
ArgumentException	The connected YubiKey does not support the permissions given, or a relying party was specified but no permissions were specified.
InvalidOperationException	The permission requires a relyingPartyId and none is given.

Remarks

See the User's Manual entry for a deeper discussion of FIDO2 authentication and how AuthTokens, PinTokens, permissions, PIN/UV, and AuthParams fit together.

See also the User's Manual entry on the SDK's AuthToken logic. That article goes into greater detail how this method, as well as other operations, perform "automatic" AuthToken retrieval based on the version of the connected YubiKey, the state of the Fido2 application on the YubiKey, the input, and the state of the Fido2Session.

This method will use the KeyCollector to obtain the PIN or prompt for user verification (fingerprint on YubiKey Bio). If no KeyCollector is loaded, then this method will throw an exception.

If the connected YubiKey does not support the option pinUvAuthToken, then there is likely no need to call this method. But if you do, the relyingPartyId arg must be null and the permissions arg must be None. To know if the YubiKey supports it, make this call.

IYubiKeyDevice yubiKeyToUse = SelectYubiKey();
using (var fido2Session = new Fido2Session(yubiKeyToUse))
{
    if (fido2Session.AuthenticatorInfo.GetOptionValue(
        AuthenticatorOptions.pinUvAuthToken) == OptionValue.True)
    {
        fido2Session.AddPermissions(
            PinUvAuthTokenPermissions.GetAssertion | PinUvAuthTokenPermissions.CredentialManagement,
            relyingPartyIdOfInterest);
    }
}

Generally, YubiKeys that support only FIDO2 version 2.0 will not support pinUvAuthToken and YubiKeys that support FIDO2 version 2.1, will support it. See also the User's Manual entry on the SDK's AuthToken logic for more details on using this method with a YubiKey that supports only FIDO2 version 2.0.

If the YubiKey does support pinUvAuthToken, then you can still call this method with no permissions (None) and a null relyingPartyId. In this case, the SDK will build a PinToken. See this User's Manual entry for a deeper discussion of PinTokens on YubiKey that supports PinUvAuthTokens. If you call with no permissions but with a relying party ID, then this method will throw an exception.

Note that if you pass in permissions of None, this method will obtain an AuthToken that has the same permission set currently set in the property PinUvAuthTokenPermissions, if there are any.

If the YubiKey supports PinUvAuthTokens, and this is called with permissions, then this method will determine if the YubiKey has UV capabilities, and if so, whether any bio verification has been enrolled. On the YubiKey, if there is a fingerprint enrolled, this method will first try to authenticate using UV, and if that fails, try to authenticate using PIN (see the FIDO2 standard, sections 6.5.5.7 and 6.5.5.7.3 step 3.10.3).

Calling this method will make sure that the AuthToken property in this class possesses the requested permissions along with any permissions specified in the AuthTokenPermissions property. To do so, this method will always obtain a new AuthToken, even if there is an AuthToken already in the object. More details are in the User's Manual entry on the SDK's AuthToken logic.

The MakeCredential and GetAssertion permissions require a relying party ID. That is, an AuthToken can be used to make a credential or get an assertion only for a specific relying party. If the permissions arg does not include MakeCredential or GetAssertion, then the relyingPartyId arg can be null. More details are in the User's Manual entry on the SDK's AuthToken logic.

It is not necessary to call this method at the beginning. However, if you do not make this call, then each time the SDK needs an AuthToken, it will obtain one with only one permission. That means that if you perform more than one operation, you might be called upon to obtain the PIN from the user, or require the user to perform user verification several times during this session.

An alternative to this method and the "automatic" AuthToken collection the SDK performs is to call TryVerifyPin(ReadOnlyMemory<byte>, PinUvAuthTokenPermissions?, string?, out int?, out bool?), TryVerifyUv(PinUvAuthTokenPermissions, string?) or some other verification method directly. However, because AuthTokens "expire" (see the User's Manual entry on AuthTokens), it is possible you will need to re-verify during a session. Hence, if you want to avoid this method or not build a KeyCollector, then you must write your code so that it calls, if needed, the appropriate Verify method before performing an operation. That is, you must then write your code so that it adheres to the permissions and expriy logic of FIDO2.