KeyCredential management functions allow the management and distribution of KeyCredentials which OPC UA Applications use to access Authorization Services and/or Brokers. An application that provides the KeyCredential management functions is called a KeyCredentialService and is typically combined with the GDS into a single application.

There are two primary models for KeyCredential management: pull and push management. In pull management, the application acts as a Client and uses the Methods on the KeyCredentialService to request and update KeyCredentials. The application is responsible for ensuring the KeyCredentials are kept up to date. In push management the application acts as a Server and exposes Methods which the KeyCredentialService can call to update the KeyCredentials as required.

A KeyCredentialService can directly manage the KeyCredentials it supplies or it may act as an intermediary between a Client and a system that does not support OPC UA such as Azure AD or LDAP.

Note that KeyCredentials are secrets that are directly passed to Authorization Services and/or Brokers and are not Certificates with private keys. Certificate distribution is managed by the Certificate management model described in 7. For example, Authorization Services that support OAuth2 often require the client to provide a client_id and client_secret parameter with any request. The KeyCredentials are the values that the application shall place in these parameters.

Pull management is performed by using a KeyCredentialManagement Object (see 8.4.3). It allows Clients to request credentials for Authorization Services or Brokers which are supported by the KeyCredentialService. The interactions between the Client and the KeyCredentialService during pull management are illustrated in Figure 16.

Figure 16 – The Pull Model for KeyCredential Management

The Application Administration component may be part of the Client or a standalone utility that understands how the Client persists its configuration information in its Configuration Database. The administration and database components are examples to illustrate how an application could be built and are not a requirement.

Requesting credentials is a two stage process because some KeyCredentialServices require a human to review and approve requests. The calls to the FinishKeyCredentialRequest Method may not be periodic and could be initiated by events such as a user starting up the application or interacting with a UI element such as a button.

KeyCredentials can only be requested for Clients which are trusted by the KeyCredentialService.

Security in pull management requires an encrypted channel and the use of administrator credentials for the KeyCredentialService that ensure only authorized users can request KeyCredentials.

Push management is performed by using a KeyCredentialConfiguration Object (see 8.5.1) which is a component of the KeyCredentialManagement Folder which is component of the ServerConfiguration Object in a Server. The interactions between the Administration application and the KeyCredentialService during push management are illustrated in Figure 17.

Figure 17 – The Push Model for KeyCredential Management

The Administration Component may use internal APIs to manage KeyCredentials or it could be a standalone utility that uses OPC UA to communicate with a Server which supports the pull model (see 8.2). The Configuration Database is used by the Server to persist its configuration information. The administration and database components are examples to illustrate how an application could be built and are not a requirement.

To ensure security of the KeyCredentials, the KeyCredentialService component can require that secrets be encrypted with a key only known to the intended recipient of the KeyCredentials. For this reason, the Administration Component uses the GetEndpoints Service to read the Certificate from the Server before initiating the credential request on behalf of the Server.

Security, when using the push management model, requires an encrypted channel and the use of administrator credentials for the Server that ensure only authorized users can update KeyCredentials. If the KeyCredentialService component is separate from the Administration Component then different administrator credentials are required for the Server that exposes the that ensure only authorized users can request new KeyCredentials on behalf of Servers.

The AddressSpace used for pull management is shown in Figure 18. Clients interact with the Nodes defined in this model when they need to request or revoke KeyCredentials for themselves or for another application. The KeyCredentialManagement Folder is a well-known Object that appears in the AddressSpace of any Server which supports KeyCredential management.

Figure 18 – The Address Space used for Pull KeyCredential Management

This Object is an instance of FolderType. It contains the KeyCredentialService Objects which may be accessed via the Server. It is the target of an Organizes reference from the Objects Folder defined in OPC 10000-5. It is defined in Table 46.

Table 46 – KeyCredentialManagement Object Definition

Attribute	Value
BrowseName	KeyCredentialManagement
Namespace	GDS (see 3.3)
TypeDefinition	FolderType defined in OPC 10000-5.
References	NodeClass	BrowseName	TypeDefinition	Modelling Rule

This ObjectType is the TypeDefinition for an Object that allows the management of KeyCredentials. It is defined in Table 47.

Table 47 – KeyCredentialServiceType Definition

Attribute	Value
BrowseName	KeyCredentialServiceType
Namespace	GDS (see 3.3)
IsAbstract	False
References	NodeClass	BrowseName	DataType	TypeDefinition	Modelling Rule
Subtype of the BaseObjectType defined in OPC 10000-5.
HasProperty	Variable	ResourceUri	String	PropertyType	Mandatory
HasProperty	Variable	ProfileUris	String[]	PropertyType	Mandatory
HasComponent	Method	StartRequest		Defined in 8.4.4.	Mandatory
HasComponent	Method	FinishRequest		Defined in 8.4.5.	Mandatory
HasComponent	Method	Revoke		Defined in 8.4.6.	Optional

The ResourceUri Property uniquely identifies the resource that accepts the KeyCredentials provided by the KeyCredentialService Object.

The ProfileUris Property specifies URIs assigned in OPC 10000-7 to the authentication mechanism used to communicate with the resource that accepts KeyCredentials provided by the Object. For example, it could specify that the resource returns JWTs using OAuth2 HTTP based APIs. As another example, it could specify an MQTT broker that expects a username/password.

The StartRequest Method is used to initiate a request for new KeyCredentials for an application. This request may complete immediately or it can require offline approval by an administrator.

The FinishRequest Method is used to complete a request created by calling StartRequest . If the KeyCredential is available it is returned. If request is not yet completed it returns Bad_NothingToDo.

The Revoke Method is used to revoke a previously issued KeyCredential.

StartRequest is used to request a new KeyCredential.

The KeyCredential secret may be encrypted with the public key of the Certificate supplied in the request. The SecurityPolicyUri specifies the security profile used for the encryption.

This Method requires an encrypted channel and that the Client provides credentials with administrative rights for the application requesting the credentials.

Signature

StartRequest (

[in] String applicationUri,

[in] ByteString certificate,

[in] String securityPolicyUri,

[in] NodeId[] requestedRoles,

[out] NodeId requestId

);

Argument	Description
applicationUri	The applicationUri of the application receiving the KeyCredentials. The request is rejected applicationUri does not uniquely identify an application known to the GDS (see 6.3.6). If the requestor is not the same as the application used to create the Secure Channel then a Certificate should be provided.
certificate	The Certificate containing the key used to encrypt the returned KeyCredential secret. This is the DER encoded form of an X.509 v3 Certificate as described in OPC 10000-6. Not specified if no encryption is required. If the securityPolicyUri is provided this field shall be provided.
securityPolicyUri	The SecurityPolicy used to encrypt the secret. If the certificate is provided this field shall be provided.
requestedRoles	A list of Roles which should be assigned to the KeyCredential. If not provided the Server chooses suitable defaults. The Server ignores Roles which it does not recognize or if the caller is not authorized to request access to the Role.
requestId	A unique identifier for the request. This identifier shall be passed to the FinishRequest (see 8.4.5).

Method Result Codes (defined in Call Service)

Result Code	Description
Bad_NotFound	The applicationUri is not known to the GDS.
Bad_ConfigurationError	The applicationUri is used by multiple records in the GDS.
Bad_CertificateInvalid	The Certificate is invalid.
Bad_SecurityPolicyRejected	The SecurityPolicy is unrecognized or not allowed or does not match the Certificate.
Bad_UserAccessDenied	The current user does not have the rights required.

Table 48 specifies the AddressSpace representation for the StartRequest Method.

Table 48 – StartRequest Method AddressSpace Definition

Attribute	Value
BrowseName	StartRequest
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory

FinishRequest is used to retrieve a KeyCredential.

If a Certificate was provided in the request then the KeyCredential secret is encrypted using an asymmetric encryption algorithm specified by the SecurityPolicyUri provided in the request.

The format of the signed and encrypted credentialSecret is the same as the Version 2 Token Secret Format defined in OPC 10000-4. When used for the credentialSecret, the signature is provided by the source of the KeyCredential which can be the GDS Application Instance Certificate. The serverNonce is a random number generated by the GDS.

If the return code is Bad_RequestNotComplete then the request has not been processed and the Client should call again. The recommended time between calls depends on the GDS.

This Method requires an encrypted channel and that the Client provides credentials with administrative rights for the application requesting the credentials.

Signature

FinishRequest (

[in] NodeId requestId,

[in] Boolean cancelRequest,

[out] String credentialId,

[out] ByteString credentialSecret,

[out] NodeId[] grantedRoles

);

Argument	Description
requestId	The identifier returned from a previous call to StartRequest.
cancelRequest	If TRUE the request is cancelled and no KeyCredentials are returned. If FALSE the normal processing proceeds.
credentialId	The unique identifier for the KeyCredential.
credentialSecret	The secret associated with the KeyCredential.
certificateThumbprint	The thumbprint of the Certificate containing the key used to encrypt the secret. Not specified if the secret is not encrypted.
securityPolicyUri	The SecurityPolicy used to encrypt the secret. If not specified the secret is not encrypted.
grantedRoles	A list of Roles which have been granted to KeyCredential. If empty then the information is not relevant or not available.

Method Result Codes (defined in Call Service)

Result Code	Description
Bad_InvalidArgument	The requestId is does not reference to a valid request for the Application.
Bad_RequestNotComplete	The request has not been processed by the Server yet..
Bad_UserAccessDenied	The current user does not have the rights required.
Bad_RequestNotAllowed	The KeyCredential manager rejected the request. The text associated with the error should indicate the exact reason.

Table 49 specifies the AddressSpace representation for the FinishRequest Method.

Table 49 – FinishRequest Method AddressSpace Definition

Attribute	Value
BrowseName	FinishRequest
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory

Revoke is used to revoke a KeyCredential used by a Server.

This Method requires an encrypted channel and that the Client provides credentials with administrative rights for the application which is having the credentials revoked.

Signature

Revoke (

[in] String credentialId

);

Argument	Description
credentialId	The unique identifier for the KeyCredential.

Method Result Codes (defined in Call Service)

Result Code	Description
Bad_InvalidArgument	The credentialId is does not reference a valid KeyCredential.
Bad_UserAccessDenied	The current user does not have the rights required.

Table 50 specifies the AddressSpace representation for the RevokeKeyCredential Method.

Table 50 – Revoke Method AddressSpace Definition

Attribute	Value
BrowseName	Revoke
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory

This abstract event is raised when an operation affecting KeyCredentials occur

This Event and it subtypes are security related and Servers shall only report them to users authorized to view security related audit events.

Its representation in the AddressSpace is formally defined in Table 52.

Table 51 – KeyCredentialAuditEventType Definition

Attribute	Value
BrowseName	KeyCredentialAuditEventType
Namespace	CORE (see 3.3)
IsAbstract	True
References	NodeClass	BrowseName	DataType	TypeDefinition	Modelling Rule
Subtype of the AuditUpdateMethodEventType defined in OPC 10000-5.
HasProperty	Variable	ResourceUri	String	PropertyType	Mandatory
HasSubtype	ObjectType	KeyCredentialRequestedAuditEventType		Defined in 8.4.8.
HasSubtype	ObjectType	KeyCredentialDeliveredAuditEventType		Defined in 8.4.9.
HasSubtype	ObjectType	KeyCredentialRevokedAuditEventType		Defined in 8.4.10.
HasSubtype	ObjectType	KeyCredentialUpdatedAuditEventType		Defined in 8.5.5.
HasSubtype	ObjectType	KeyCredentialDeletedAuditEventType		Defined in 8.5.6.

This EventType inherits all Properties of the AuditUpdateMethodEventType. Their semantic is defined in OPC 10000-5.

The ResourceUri Property specifies the URI for the resource which accepts the KeyCredential.

This event is raised when a new KeyCredential request has been accepted or rejected by the Server.

This can be the result of a StartKeyCredentialRequest Method call.

Its representation in the AddressSpace is formally defined in Table 52.

Table 52 – KeyCredentialRequestedAuditEventType Definition

Attribute	Value
BrowseName	KeyCredentialRequestedAuditEventType
Namespace	GDS (see 3.3)
IsAbstract	False
References	NodeClass	BrowseName	DataType	TypeDefinition	Modelling Rule
Subtype of the KeyCredentialAuditEventType defined in 8.4.7.

This EventType inherits all Properties of the KeyCredentialAuditEventType.

This event is raised when a KeyCredential is delivered by the Server to an application.

This is the result of a FinishKeyCredentialRequest Method completing.

Its representation in the AddressSpace is formally defined in Table 53.

Table 53 – KeyCredentialDeliveredAuditEventType Definition

Attribute	Value
BrowseName	KeyCredentialDeliveredAuditEventType
Namespace	GDS (see 3.3)
IsAbstract	False
References	NodeClass	BrowseName	DataType	TypeDefinition	Modelling Rule
Subtype of the KeyCredentialAuditEventType defined in 8.4.7.

This EventType inherits all Properties of the KeyCredentialAuditEventType.

This event is raised when a KeyCredential is revoked.

This is the result of a RevokeKeyCredential Method completing.

Its representation in the AddressSpace is formally defined in Table 54.

Table 54 – KeyCredentialRevokedAuditEventType Definition

Attribute		Value
BrowseName		KeyCredentialRevokedAuditEventType
Namespace		GDS (see 3.3)
IsAbstract		False
References	NodeClass		BrowseName	DataType	TypeDefinition	Modelling Rule
Subtype of the KeyCredentialAuditEventType defined in 8.4.7.

This EventType inherits all Properties of the KeyCredentialAuditEventType.

The AddressSpace used for push management is shown in Figure 19. Clients interact with the Nodes defined in this model when they need update the KeyCredentials used by a Server to access resources such as Brokers or Authorization Servers. The NetworkResources Folder is a well-known Object that appears in the AddressSpace of any Server which supports KeyCredential management.

Figure 19 – The Address Space used for Push KeyCredential Management

This Object is an instance of FolderType. It contains The Objects which make be accessed via the Server. It is the target of an HasComponent reference from the ServerConfiguration Object defined in 7.7.2. It is defined in Table 46.

Table 55 – KeyCredentialConfiguration Object Definition

Attribute	Value
BrowseName	KeyCredentialConfiguration
Namespace	CORE (see 3.3)
TypeDefinition	FolderType defined in OPC 10000-5.
References	NodeClass	BrowseName	TypeDefinition		Modelling Rule

This ObjectType is the TypeDefinition for an Object that allows the configuration of KeyCredentials used by the Server. It also includes basic status information which report problems accessing the resource that might be related to bad KeyCredentials. It is defined in Table 56.

Table 56 – KeyCredentialConfigurationType Definition

Attribute	Value
BrowseName	KeyCredentialConfigurationType
Namespace	CORE (see 3.3)
IsAbstract	False
References	NodeClass	BrowseName	DataType	TypeDefinition	Modelling Rule
Subtype of the BaseObjectType defined in OPC 10000-5.
HasProperty	Variable	ResourceUri	String	PropertyType	Mandatory
HasProperty	Variable	ProfileUri	String	PropertyType	Mandatory
HasProperty	Variable	EndpointUrls	String[]	PropertyType	Optional
HasProperty	Variable	ServiceStatus	StatusCode	PropertyType	Optional
HasComponent	Method	GetEncryptingKey		Defined in 8.5.8.	Optional
HasComponent	Method	UpdateCredential		Defined in 8.5.3.	Optional
HasComponent	Method	DeleteCredential		Defined in 8.5.4.	Optional

The ResourceUri Property uniquely identifies the resource that accepts the KeyCredentials.

The ProfileUri Property specifies the protocol used to access the resource.

The EndpointUrls Property specifies the URLs that the Server uses to access the resource.

The ServiceStatus Property indicates the result of the last attempt to communicate with the resource. The following common error values are defined:

ServiceStatus	Description
Bad_OutOfService	Communication was not attempted by the Server because Enabled is FALSE.
Bad_IdentityTokenRejected	Communication failed because the KeyCredentials are not valid.
Bad_NoCommunication	Communication failed because the endpoint is not reachable. Where possible a more specific error code should be used. See OPC 10000-4 for a complete list of standard StatusCodes.

The GetEncryptingKey Method is used request a Public Key that can be used to encrypt the KeyCredentials.

The UpdateKeyCredential Method is used to change the KeyCredentials used by the Server.

UpdateCredential is used to update a KeyCredential used by a Server.

The KeyCredential secret may be encrypted with the public key returned by GetEncryptingKey. The SecurityPolicyUri species the algorithm used for encryption. The format of the encrypted data is described in 8.5.8.

This Method requires an encrypted channel and that the Client provides credentials with administrative rights on the Server.

Signature

UpdateCredential(

[in] String credentialId,

[in] ByteString credentialSecret,

[in] String certificateThumbprint,

[in] String securityPolicyUri

);

Argument	Description
credentialId	The unique identifier associated with the KeyCredential.
credentialSecret	The secret associated with the KeyCredential.
certificateThumbprint	The thumbprint of the Certificate used to encrypt the secret. For RSA SecurityPolicies this shall be one of the Application Instance Certificates assigned to the Server. For ECC SecurityPolicies this field is not specified.Not specified if the secret is not encrypted.
securityPolicyUri	The SecurityPolicy used to encrypt the secret. If not specified the secret is not encrypted.

Method Result Codes (defined in Call Service)

Result Code	Description
Bad_InvalidArgument	The credentialId or credentialSecret is not valid.
Bad_CertificateInvalid	The Certificate is invalid or it is not one of the Server’s Certificates.
Bad_SecurityPolicyRejected	The SecurityPolicy is unrecognized or not allowed.
Bad_UserAccessDenied	The current user does not have the rights required.

Table 57 specifies the AddressSpace representation for the UpdateKeyCredential Method.

Table 57 – UpdateCredential Method AddressSpace Definition

Attribute	Value
BrowseName	UpdateCredential
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory

DeleteCredential is used to delete a KeyCredential used by a Server.

This Method requires an encrypted channel and that the Client provides credentials with administrative rights on the Server.

Signature

DeleteCredential()

Method Result Codes (defined in Call Service)

Result Code	Description
Bad_UserAccessDenied	The current user does not have the rights required.

Table 58 specifies the AddressSpace representation for the DeleteKeyCredential Method.

Table 58 – DeleteCredential Method AddressSpace Definition

Attribute	Value
BrowseName	DeleteCredential
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule

This event is raised when a KeyCredential is updated.

This Event and its subtypes report sensitive security related information. Servers shall only report these Events to Clients which are authorized to view such information.

This is the result of a UpdateCredential Method completing.

Its representation in the AddressSpace is formally defined in Table 59.

Table 59 – KeyCredentialUpdatedAuditEventType Definition

Attribute	Value
BrowseName	KeyCredentialUpdatedAuditEventType
Namespace	CORE (see 3.3)
IsAbstract	False
References	NodeClass	BrowseName	DataType	TypeDefinition	Modelling Rule
Subtype of the KeyCredentialAuditEventType defined in 8.4.7.

This EventType inherits all Properties of the KeyCredentialAuditEventType.

This event is raised when a KeyCredential is updated.

This is the result of a DeleteCredential Method completing.

Its representation in the AddressSpace is formally defined in Table 60.

Table 60 – KeyCredentialUpdatedAuditEventType Definition

Attribute	Value
BrowseName	KeyCredentialDeletedAuditEventType
Namespace	CORE (see 3.3)
IsAbstract	False
References	NodeClass	BrowseName	DataType	TypeDefinition	Modelling Rule
Subtype of the KeyCredentialAuditEventType defined in 8.4.7.

This EventType inherits all Properties of the KeyCredentialAuditEventType. GetEncryptingKey

GetEncryptingKey is used to request a key that can be used to encrypt a KeyCredential.

This Method requires an encrypted channel and that the Client provides credentials with administrative rights on the Server.

Signature

GetEncryptingKey(

[in] String credentialId,

[in] String requestedSecurityPolicyUri,

[out] ByteString publicKey,

[out] String revisedSecurityPolicyUri

);

Argument	Description
credentialId	The unique identifier associated with the KeyCredential.
requestedSecurityPolicyUri	The SecurityPolicy used to encrypt the secret. If not specified the Server chooses a suitable default.
publicKey	The Public Key used to encrypt the secret. The format depends on the SecurityPolicyUri.
revisedSecurityPolicyUri	The SecurityPolicy used to encrypt the secret. It also specifies the contents of the publicKey. This may be different from the requestedSecurityPolicyUri.

Method Result Codes (defined in Call Service)

Result Code	Description
Bad_InvalidArgument	The credentialId is not valid.
Bad_UserAccessDenied	The current user does not have the rights required.

Table 60a specifies the AddressSpace representation for the GetEncryptingKey Method.

Table 60a – GetEncryptingKey Method AddressSpace Definition

Attribute	Value
BrowseName	GetEncryptingKey
References	NodeClass	BrowseName	DataType	TypeDefinition	ModellingRule
HasProperty	Variable	InputArguments	Argument[]	PropertyType	Mandatory
HasProperty	Variable	OutputArguments	Argument[]	PropertyType	Mandatory