Package com.authlete.common.dto

Class CredentialOfferCreateRequest

  • All Implemented Interfaces:
    Serializable
    public class CredentialOfferCreateRequest
extends Object
implements Serializable
    Request to Authlete's /vci/offer/create API.

    The API is used to create a credential offer.

    A credential offer is a JSON object that is used as the value of the credential_offer parameter sent to the credential offer endpoint of the wallet or is returned from an endpoint designated by the credential_offer_uri parameter.

    A credential offer looks like below. Properties in this class (= request parameters to the /vci/offer/create API) are used to control the content of the credential offer being created. 

     {
   "credential_issuer": "...",
   "credentials": [ ... ],
   "grants": {
     "authorization_code": {
       "issuer_state": "..."
     },
     "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
       "pre-authorized_code": "...",
       "user_pin_required": true
     }
   }
 }

    Breaking Changes

    The "OpenID for Verifiable Credential Issuance" specification tends to repeat breaking changes. Such changes affect this Java class.

    In the past draft of the specification, elements in the "credentials" array in a credential offer are either strings or JSON objects. Therefore, the type of the "credentials" property in the previous implementation of this class was a "string" whose content must be able to be parsed as a JSON array. However, as a result of a breaking change in the specification, it is ensured that all elements in the "credentials" array in a credential offer are strings. To make it easier to treat the "credentials" property of this class, the type of the property has been changed from a string to an array of strings.

    Since:
    3.59, Authlete 3.0
    See Also:
    OpenID for Verifiable Credential Issuance, Serialized Form

    • Constructor Detail

      • CredentialOfferCreateRequest

        public CredentialOfferCreateRequest()

    • Method Detail

      • getCredentials

        public String[] getCredentials()
        Get the value of the credentials array. 
         {
   "credential_issuer": "...",
   "credentials": [ ... ],
   "grants": { ... }
 }

        This property is mandatory.

        The type of the object returned from this method has been changed from String to String[] since version 3.86 to align with the breaking change of the OID4VCI specification.

        Returns:
        The value of the credentials array.

      • setCredentials

        public CredentialOfferCreateRequest setCredentials​(String[] credentials)
        Set the value of the credentials array. 
         {
   "credential_issuer": "...",
   "credentials": [ ... ],
   "grants": { ... }
 }

        This property is mandatory.

        Parameters:
        credentials - The value of the credentials array.
        Returns:
        this object.
        Since:
        3.86

      • isAuthorizationCodeGrantIncluded

        public boolean isAuthorizationCodeGrantIncluded()
        Get the flag to include the authorization_code object in the grants object. 
         {
   "credential_issuer": "...",
   "credentials": [ ... ],
   "grants": {
     "authorization_code": { ... }
   }
 }
        Returns:
        true if the authorization_code object will be included.

      • setAuthorizationCodeGrantIncluded

        public CredentialOfferCreateRequest setAuthorizationCodeGrantIncluded​(boolean included)
        Set the flag to include the authorization_code object in the grants object. 
         {
   "credential_issuer": "...",
   "credentials": [ ... ],
   "grants": {
     "authorization_code": { ... }
   }
 }
        Parameters:
        included - true to include the authorization_code object.
        Returns:
        this object.

      • isIssuerStateIncluded

        public boolean isIssuerStateIncluded()
        Get the flag to include the issuer_state property in the authorization_code object in the grants object. 
         {
   "credential_issuer": "...",
   "credentials": [ ... ],
   "grants": {
     "authorization_code": {
       "issuer_state": "..."
     }
   }
 }

        When this property is true, Authlete generates an issuer state and puts it in the authorization_code object as the value of the issuer_state property.

        Returns:
        true if the issuer_state property will be included.

      • setIssuerStateIncluded

        public CredentialOfferCreateRequest setIssuerStateIncluded​(boolean included)
        Set the flag to include the issuer_state property in the authorization_code object in the grants object. 
         {
   "credential_issuer": "...",
   "credentials": [ ... ],
   "grants": {
     "authorization_code": {
       "issuer_state": "..."
     }
   }
 }

        When this property is true, Authlete generates an issuer state and puts it in the authorization_code object as the value of the issuer_state property.

        Parameters:
        included - true to include the issuer_state property.
        Returns:
        this object.

      • isPreAuthorizedCodeGrantIncluded

        public boolean isPreAuthorizedCodeGrantIncluded()
        Get the flag to include the urn:ietf:params:oauth:grant-type:pre-authorized_code object in the grants object. 
         {
   "credential_issuer": "...",
   "credentials": [ ... ],
   "grants": {
     "urn:ietf:params:oauth:grant-type:pre-authorized_code": { ... }
   }
 }

        When this property is true, the urn:ietf:params:oauth:grant-type:pre-authorized_code object is included. In addition, Authlete generates a pre-authorized code and puts it in the urn:ietf:params:oauth:grant-type:pre-authorized_code object as the value of the pre-authorized_code property. Note that the specification requires that the pre-authorized_code property exist whenever the urn:ietf:params:oauth:grant-type:pre-authorized_code object is included.

        Returns:
        true if the urn:ietf:params:oauth:grant-type:pre-authorized_code object will be included.

      • setPreAuthorizedCodeGrantIncluded

        public CredentialOfferCreateRequest setPreAuthorizedCodeGrantIncluded​(boolean included)
        Set the flag to include the urn:ietf:params:oauth:grant-type:pre-authorized_code object in the grants object. 
         {
   "credential_issuer": "...",
   "credentials": [ ... ],
   "grants": {
     "urn:ietf:params:oauth:grant-type:pre-authorized_code": { ... }
   }
 }

        When this property is true, the urn:ietf:params:oauth:grant-type:pre-authorized_code object is included. In addition, Authlete generates a pre-authorized code and puts it in the urn:ietf:params:oauth:grant-type:pre-authorized_code object as the value of the pre-authorized_code property. Note that the specification requires that the pre-authorized_code property exist whenever the urn:ietf:params:oauth:grant-type:pre-authorized_code object is included.

        Parameters:
        included - true to include the urn:ietf:params:oauth:grant-type:pre-authorized_code object.
        Returns:
        this object.

      • isUserPinRequired

        public boolean isUserPinRequired()
        Get the flag to include the user_pin_required property with the value true. 
         {
   "credential_issuer": "...",
   "credentials": [ ... ],
   "grants": {
     "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
       "pre-authorized_code": "...",
       "user_pin_required": true
     }
   }
 }
        Returns:
        true if the user_pin_required property will be included with the value true. false if the property will be omitted.

      • setUserPinRequired

        public CredentialOfferCreateRequest setUserPinRequired​(boolean included)
        Set the flag to include the user_pin_required property with the value true. 
         {
   "credential_issuer": "...",
   "credentials": [ ... ],
   "grants": {
     "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
       "pre-authorized_code": "...",
       "user_pin_required": true
     }
   }
 }
        Parameters:
        included - true to include the user_pin_required property with the value true. false to omit the property.
        Returns:
        this object.

      • getUserPinLength

        public int getUserPinLength()
        Get the length of the user PIN associated with the credential offer.

        Authlete generates a user PIN of the specified length when necessary. The maximum length that can be specified is 8 as the specification requires so. When this property is omitted or its value is 0 or negative, the value of the userPinLength property of the service is used.

        Returns:
        The length of the user PIN.
        See Also:
        Service.getUserPinLength()

      • setUserPinLength

        public CredentialOfferCreateRequest setUserPinLength​(int length)
        Set the length of the user PIN associated with the credential offer.

        Authlete generates a user PIN of the specified length when necessary. The maximum length that can be specified is 8 as the specification requires so. When this property is omitted or its value is 0 or negative, the value of the userPinLength property of the service is used.

        Parameters:
        length - The length of the user PIN.
        Returns:
        this object.
        See Also:
        Service.setUserPinLength(int)

      • getSubject

        public String getSubject()
        Get the subject associated with the credential offer.

        This property is mandatory.

        Returns:
        The subject associated with the credential offer.

      • setSubject

        public CredentialOfferCreateRequest setSubject​(String subject)
        Set the subject associated with the credential offer.

        This property is mandatory.

        Parameters:
        subject - The subject associated with the credential offer.
        Returns:
        this object.

      • getDuration

        public long getDuration()
        Get the duration of the credential offer in seconds.

        If this property holds a positive integer, the value is used as the duration of the credential offer being issued. Otherwise, the value of the credentialOfferDuration property of the service is used.

        Returns:
        The duration of the credential offer in seconds.
        See Also:
        Service.getCredentialOfferDuration()

      • setDuration

        public CredentialOfferCreateRequest setDuration​(long duration)
        Set the duration of the credential offer in seconds.

        If this property holds a positive integer, the value is used as the duration of the credential offer being issued. Otherwise, the value of the credentialOfferDuration property of the service is used.

        Parameters:
        duration - The duration of the credential offer in seconds.
        Returns:
        this object.
        See Also:
        Service.setCredentialOfferDuration(long)

      • getContext

        public String getContext()
        Get the general-purpose arbitrary string associated with the credential offer.

        Developers can utilize this property as they like. Authlete does not care about the content.

        Returns:
        The general-purpose arbitrary string.

      • setContext

        public CredentialOfferCreateRequest setContext​(String context)
        Set the general-purpose arbitrary string associated with the credential offer.

        Developers can utilize this property as they like. Authlete does not care about the content.

        Parameters:
        context - The general-purpose arbitrary string.
        Returns:
        this object.

      • getProperties

        public Property[] getProperties()
        Get the extra properties associated with the credential offer. Extra properties are general-purpose key-value pairs.

        The extra properties will be eventually associated with an access token which will be created based on the credential offer.

        Returns:
        The extra properties associated with the credential offer.
        Since:
        3.62

      • setProperties

        public CredentialOfferCreateRequest setProperties​(Property[] properties)
        Set the extra properties associated with the credential offer. Extra properties are general-purpose key-value pairs.

        The extra properties will be eventually associated with an access token which will be created based on the credential offer.

        Parameters:
        properties - The extra properties associated with the credential offer.
        Returns:
        this object.
        Since:
        3.62

      • getJwtAtClaims

        public String getJwtAtClaims()
        Get the additional claims in JSON object format that are added to the payload part of the JWT access token.

        This request parameter has a meaning only when the format of access tokens issued by the service is JWT. In other words, it has a meaning only when the accessTokenSignAlg property of the Service holds a non-null value. See the description of the getAccessTokenSignAlg() method for details.

        The additional claims will be eventually associated with an access token which will be created based on the credential offer.

        Returns:
        Additional claims that are added to the payload part of the JWT access token.
        Since:
        3.62

      • setJwtAtClaims

        public CredentialOfferCreateRequest setJwtAtClaims​(String claims)
        Set the additional claims in JSON object format that are added to the payload part of the JWT access token.

        This request parameter has a meaning only when the format of access tokens issued by the service is JWT. In other words, it has a meaning only when the accessTokenSignAlg property of the Service holds a non-null value. See the description of the getAccessTokenSignAlg() method for details.

        The additional claims will be eventually associated with an access token which will be created based on the credential offer.

        Parameters:
        claims - Additional claims that are added to the payload part of the JWT access token.
        Returns:
        this object.
        Since:
        3.62

      • getAuthTime

        public long getAuthTime()
        Get the time when the user authentication was performed during the course of issuing the credential offer.
        Returns:
        The time of the user authentication in seconds since the Unix epoch.
        Since:
        3.62

      • setAuthTime

        public CredentialOfferCreateRequest setAuthTime​(long authTime)
        Set the time when the user authentication was performed during the course of issuing the credential offer.
        Parameters:
        authTime - The time of the user authentication in seconds since the Unix epoch. Must not be negative.
        Returns:
        this object.
        Since:
        3.62

      • getAcr

        public String getAcr()
        Get the Authentication Context Class Reference of the user authentication performed during the course of issuing the credential offer.
        Returns:
        The Authentication Context Class Reference.
        Since:
        3.62

      • setAcr

        public CredentialOfferCreateRequest setAcr​(String acr)
        Set the Authentication Context Class Reference of the user authentication performed during the course of issuing the credential offer.
        Parameters:
        acr - The Authentication Context Class Reference.
        Returns:
        this object.
        Since:
        3.62