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": "...",
   "credential_configuration_ids": [ ... ],
   "grants": {
     "authorization_code": {
       "issuer_state": "..."
     },
     "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
       "pre-authorized_code": "...",
       "tx_code": {
         "input_mode": "numeric",
         "length": 6,
         "description": "..."
       }
     }
   }
 }

    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.

    Due to another breaking change made in December 2023, the credentials property in a credential offer has been renamed to credential_configurations. In addition, the user_pin_required boolean property has been replaced with the tx_code JSON object.

    Another breaking change. The credential_configurations property in a credential offer has been renamed to credential_configuration_ids. (January, 2024)

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

    • Constructor Detail

      • CredentialOfferCreateRequest

        public CredentialOfferCreateRequest()

    • Method Detail

      • getCredentialConfigurationIds

        public String[] getCredentialConfigurationIds()
        Get the value of the credential_configuration_ids array. 
         {
   "credential_issuer": "...",
   "credential_configuration_ids": [ ... ],
   "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.

        NOTE: Due to the breaking change made in December 2023, the credentials property in a credential offer has been renamed to credential_configurations.

        Another breaking change. The credential_configurations property has been renamed to credential_configuration_ids. (January, 2024)

        Returns:
        The value of the credential_configuration_ids array.
        Since:
        3.94

      • setCredentialConfigurationIds

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

        This property is mandatory.

        NOTE: Due to the breaking change made in December 2023, the credentials property in a credential offer has been renamed to credential_configurations.

        Another breaking change. The credential_configurations property has been renamed to credential_configuration_ids. (January, 2024)

        Parameters:
        ids - The value of the credential_configuration_ids array.
        Returns:
        this object.
        Since:
        3.94

      • isAuthorizationCodeGrantIncluded

        public boolean isAuthorizationCodeGrantIncluded()
        Get the flag to include the authorization_code object in the grants object. 
         {
   "credential_issuer": "...",
   "credential_configuration_ids": [ ... ],
   "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": "...",
   "credential_configuration_ids": [ ... ],
   "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": "...",
   "credential_configuration_ids": [ ... ],
   "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": "...",
   "credential_configuration_ids": [ ... ],
   "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": "...",
   "credential_configuration_ids": [ ... ],
   "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": "...",
   "credential_configuration_ids": [ ... ],
   "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.

      • 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

      • getTxCode

        public String getTxCode()
        Get the transaction code that should be associated with the credential offer.

        If this parameter is not empty and the preAuthorizedCodeGrantIncluded parameter is true, the urn:ietf:params:oauth:grant-type:pre-authorized_code object will include the tx_code object.

        The length of the value of this parameter will be used as the value of the length property in the tx_code object. 

         {
   "credential_issuer": "...",
   "credential_configuration_ids": [ ... ],
   "grants": {
     "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
       "pre-authorized_code": "...",
       "tx_code": {
         "length": length
       }
     }
   }
 }
        Returns:
        The transaction code.
        Since:
        3.91

      • setTxCode

        public CredentialOfferCreateRequest setTxCode​(String txCode)
        Set the transaction code that should be associated with the credential offer.

        If this parameter is not empty and the preAuthorizedCodeGrantIncluded parameter is true, the urn:ietf:params:oauth:grant-type:pre-authorized_code object will include the tx_code object.

        The length of the value of this parameter will be used as the value of the length property in the tx_code object. 

         {
   "credential_issuer": "...",
   "credential_configuration_ids": [ ... ],
   "grants": {
     "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
       "pre-authorized_code": "...",
       "tx_code": {
         "length": length
       }
     }
   }
 }
        Parameters:
        txCode - The transaction code.
        Returns:
        this object.
        Since:
        3.91

      • getTxCodeInputMode

        public String getTxCodeInputMode()
        Get the input mode of the transaction code.

        The value of this property will be used as the value of the input_mode property in the tx_code object. 

         {
   "credential_issuer": "...",
   "credential_configuration_ids": [ ... ],
   "grants": {
     "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
       "pre-authorized_code": "...",
       "tx_code": {
         "length": length,
         "input_mode": "..."
       }
     }
   }
 }
        Returns:
        The input mode of the transaction code.
        Since:
        3.91

      • setTxCodeInputMode

        public CredentialOfferCreateRequest setTxCodeInputMode​(String inputMode)
        Set the input mode of the transaction code.

        The value of this property will be used as the value of the input_mode property in the tx_code object. 

         {
   "credential_issuer": "...",
   "credential_configuration_ids": [ ... ],
   "grants": {
     "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
       "pre-authorized_code": "...",
       "tx_code": {
         "length": length,
         "input_mode": "..."
       }
     }
   }
 }

        Possible values listed in the current draft of the OID4VCI specification are "numeric" and "text" only, but the /vci/offer/create API accepts other values for the future extension in addition to the predefined ones.

        Parameters:
        inputMode - The input mode of the transaction code.
        Returns:
        this object.
        Since:
        3.91

      • getTxCodeDescription

        public String getTxCodeDescription()
        Get the description of the transaction code.

        The value of this property will be used as the value of the description property in the tx_code object. 

         {
   "credential_issuer": "...",
   "credential_configuration_ids": [ ... ],
   "grants": {
     "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
       "pre-authorized_code": "...",
       "tx_code": {
         "length": length,
         "description": "..."
       }
     }
   }
 }
        Returns:
        The description of the transaction code.
        Since:
        3.91

      • setTxCodeDescription

        public CredentialOfferCreateRequest setTxCodeDescription​(String description)
        Set the description of the transaction code.

        The value of this property will be used as the value of the description property in the tx_code object. 

         {
   "credential_issuer": "...",
   "credential_configuration_ids": [ ... ],
   "grants": {
     "urn:ietf:params:oauth:grant-type:pre-authorized_code": {
       "pre-authorized_code": "...",
       "tx_code": {
         "length": length,
         "description": "..."
       }
     }
   }
 }
        Parameters:
        description - The description of the transaction code. The length of the description must not exceed 300.
        Returns:
        this object.
        Since:
        3.91