Artifacts and User Stories Definitions

On this page you can find the definition of the standard Alastria ID objects, namely Alastria Token(AT), Alastria Session (AS) and Alastria Identity Creation (AIC); and the technicals details of the Alastria ID Workflows, including some detailled sequence diagrams.

Still work in progress.

0. Artifacts Definition

Alastria Artifacts are currently coded as JWT objects, so following JWT specifications they are structured in three parts:

Header
Payload
Signature

WHen required (i.e.: communication) Alastria JWT objects are represented as three Base64url parts concatenated with ‘.’ (xxxxx.yyyyy.zzzzz)

HEADER

The header must be composed of:

Token type (“typ”: Type)
Hashing Algorithm (“alg”: Algorithm)
Key identifier (“kid”) It is an optional field with a public key identifier
Public key (“jwk”) It is an optional field with the public key used to sign the JWT in a standard format JWK (https://www.rfc-editor.org/rfc/rfc7517) Header example:

{
    "alg": "ES256K",
    "typ": "JWT",
    "kid": "did:ala:quor:redt:QmeeasCZ9jLbX...ueBJ7d7csxhb#keys-1",
    "jwk": {"keys": [
         {"kty":"OKP",
          "alg": "EdDSA",
          "crv":"Ed25519",
          "x":"MKBCTNIcKUSDii11ySs3526iDZ8AiTo7Tu6KPAqv7D4",
          "y":"4Etl6SRW2YiLUrN5vfvVHuhp7x8PxltmWWlbbM4IFyM",
          "use":"sig",
          "kid":"-1909572257"}
       ]
     }
}

Valid algorithm are as follow:

HS256 HMAC using SHA-256 hash algorithm
HS384 HMAC using SHA-384 hash algorithm
HS512 HMAC using SHA-512 hash algorithm
RS256 RSASSA using SHA-256 hash algorithm
RS384 RSASSA using SHA-384 hash algorithm
RS512 RSASSA using SHA-512 hash algorithm
ES256 ECDSA using P-256 curve and SHA-256 hash algorithm
ES384 ECDSA using P-384 curve and SHA-384 hash algorithm
ES512 ECDSA using P-521 curve and SHA-512 hash algorithm
none No digital signature or MAC value included

PAYLOAD

The payload content depends on the Alastria artifact type: Alastria Token (AT), Alastria Session (AS) and Alastria Identity Creation (AIC). They are specified in the corresponding sections.

SIGNATURE

Signature includes header and payload and must use the hashing algorithm specified in the header.

WHen HMAC a secret sharing signature is used:

HMACSHA256( base64UrlEncode(header) + "." + base64UrlEncode(payload), secret)

WHen RSA or ECDSA is used, the signature is performed using the sender Private key so the identity of the sender is proofed. Ethereum uses SHA3-256 (RSASHA256) algorithm that is the recommended algorithm.

RSASHA256( base64UrlEncode(header) + "." + base64UrlEncode(payload), RSA private key)

0.1 Alastria Token (AT)

Header and signature parts follow JWT rules as explained in section 0. Objects Definition

PAYLOAD

The following fields are mandatory:

“iss”: Issuer. Alastria DID of the sender (issuer) of the AT, could be an Issuer or a Service Provider in Alastria ID model terms.
“gwu”: GatewayURL. Sender's url gateway, also known as "Alastria Open Access". The Wallet should store any gwu it receives along with the provider name so the user can select witch one to use.
“cbu”: CallbackURL. Callback URL to which subject answer (including user public key) should be addressed.
“iat”: IssueAt. Issuance date of the AT.
“exp”: ExpirationTime. The Expiration time of the AT. 2021/10/05 Clarification. This is a technical expiration field, it means that the object cannot be processed after the expiration date. It does not reflect the validity of the data contained in the object, if any.

The following standard JWT fields are recommended but optional:

"@context": It should be at least "https://alastria.github.io/identity/artifacts/v1", more urls with other specifications are allowed (it is optional as it is a new addition in this artifact)
"type": It should be at least "AlastriaToken" (it is optional as it is a new addition in this artifact)
- It is also possible to add the use flow for this artifact, for AT valid values are:
  - US12: Identity Creation
  - US211: Authentication
  - US221: Credential Issuance
  - US231: Present presentation (this will change shortly)
  - US142: Legacy ID and Alastria ID vinculation
“nbf”: NotBefore. Token activation date
“jti”: JWTID. JWT unique identifier
"mfau": MFA (Multi Factor Authentication) URL. An optional URL for MFA callbacks, improves security in stories like US 1.2 Identity Creation

Alastria Token payload examples:

{
"jti ": "slfkjs-0923-...",
"iss": ""did:ala:quor:redT:bc0..."",
"gwu": "http://www.gateway_socio.com",
"cbu": "http://www.backend_service_provider.com/callback",
"iat": 14344660338,
"exp": 15346639338,
"nbf": 14344660338
}

{
  "type": ["AlastriaToken","US12"],
  "@context": ["https://alastria.github.io/identity/artifacts/v1"],
  "nbf": 1587712704319,
  "gwu": "http://url/rpc",
  "cbu": "http://url/loginAID",
  "iss": "did:ala:quor:redT:3235c170482ff9ca250fb2a3b83468cb605f6a4c",
  "exp": 1587799104319,
  "iat": 1587712704319,
  "jti": "ze298y42sba",
  "mfau": "http://url/mfa_server"

}

0.2 Alastria Session (AS)

Header and signature parts follow JWT rules as explained in section 0. Objects Definition

PAYLOAD

The following fields are mandatory:

"@context": It should be at least "https://alastria.github.io/identity/artifacts/v1", more urls with other specifications are allowed
"type": It should be at least "AlastriaSession"
- It is also possible to add the use flow for this artifact, for AS valid values are:
  - US211: Authentication
  - US221: Credential Issuance
  - US231: Present Presentation
  - US142: Legacy ID and Alastria ID vinculation
“iss”: Issuer. DID of the issuer of the Alastria Session. It is usually the subject/user in Alastria ID model.
"alastriaToken": VerifiedAT. Coded as a 64BaseURL JWT. The original [Alastria Token (AT)](0.1 Alastria Token (AT)) to which this Alastria Session is sent as answer.

The following standard JWT fields are recommended but optional:

"jti"
"iat"
"exp" 2021/10/05 Clarification. This is a technical expiration field, it means that the object cannot be processed after the expiration date. It does not reflect the validity of the data contained in the object, if any.
"nbf"

Alastria Session payload example:

{
  "jti": "ze298y42sba"  
  "@context": ["https://alastria.github.io/identity/artifacts/v1"],
  "type": ["AlastriaSession","US211"]
  "iss": "did:ala:quor:redT:07dba616e17a45fca5cfc999a584180e45353aa9",
  "iat": 1587712763,
  "exp": 1563783392,
  "nbf": 1563783392,
  "alastriaToken": "eyJ0..4ea8",
}

0.3 Alastria Identity Creation (AIC)

Is the JWT object sent by the subject from his/her wallet to register an Alastria DID, thus completing the creation of an Alastria ID. Header and signature parts follow JWT rules as explained in section 0. Objects Definition

PAYLOAD

The following fields are mandatory:

"@context": It should be at least "https://alastria.github.io/identity/artifacts/v1", more urls with other specifications are allowed
"type": It should be "AlastriaIdentityCreation"
- It is also possible to add the use flow for this artifact, for AIC valid values are:
  - US12: Alastria Identity Creation
"createAlastriaTX": Hex coded (with initial 0x) createAlastriaID Transaction, signed by the subject.
"alastriaToken": Originally received (coded as a 64BaseURL) Alastria Token JWT, the Alastria token is not signed by the subject, because it is included in a subject signed JWT, the AIC.
"publicKey": Hex coded (with initial 0x) Subject's Public Key.

The following standard JWT fields are recommended but optional:

"jti"
"iat"
"exp" 2021/10/05 Clarification. This is a technical expiration field, it means that the object cannot be processed after the expiration date. It does not reflect the validity of the data contained in the object, if any.
"nbf"

Alastria Identity Creation payload examples:

{
  "@context": ["https://alastria.github.io/identity/artifacts/v1"],
  "type": ["AlastriaIdentityCreation","US12"],
  "createAlastriaTX":"0xf9...",
  "alastriaToken":"ey...",
  "publicKey":"0x2e...",
  "jti": "ze298y42sba",
  "iat": 1587712763,
  "exp": 1563783392,
  "nbf": 1563783392
}

{
"@context": ["https://alastria.github.io/identity/artifacts/v1"],
  "type": ["AlastriaIdentityCreation"],
  "createAlastriaTX": 
"0xf901888203af80830927c094bd4a2c84edb97be5beff7cd341bd63567e73f8c980b901246d69d99a000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000c450382c1a000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000803265353037616630313136376339386136616363633063643436616232613235366464366236633639656331633063323866383066623632653166376437303233333736386230633538646262646163316663333538623831343163303735613532303438336366393737396534656139386431336466323833336633373637000000000000000000000000000000000000000000000000000000001ba0ba71cde488ee7ce6c0547f64c89fbc5a5c4e60eb99afad69d0ae73cd16d1ead1a06deb0a6ad9e4c4e5eaa15448fb22f9d817905124f5368216cdfc6364ed005ccb",
  "alastriaToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJFUzI...",
  "publicKey": "0x2e507af01167c98a6accc0cd46ab2a256dd6b6c69ec1c0c28f80fb62e1f7d70233768b0c58dbbdac1fc358b8141c075a520483cf9779e4ea98d13df2833f3767"
}

0.4 Alastria Identity Recovery (AIR)

Is the JWT object sent by the subject from his/her wallet to recover Alastria ID whose control has been lost (theft, lost, etc). Header and signature parts follow JWT rules as explained in 0. Objects Definition

PAYLOAD

The following fields are mandatory:

"@context": It should be at least "https://alastria.github.io/identity/artifacts/v1", more urls with other specifications are allowed
"type": It should be "AlastriaIdentityRecovery"
- It is also possible to add the use flow for this artifact, for AIR valid values are:
  - US31: Identity Recovery
"recoverAlastriaTX": Hex coded (with initial 0x) recoverAlastriaID Transaction, signed by the subject with the new Private Key.
"alastriaToken": Originally received (coded as a 64BaseURL) Alastria Token JWT, the Alastria token is not signed by the subject, because it is included in a subject signed JWT, the AIR.
"publicKey": Hex coded (with initial 0x) Subject's Public Key.

The following standard JWT fields are recommended but optional:

"jti"
"iat"
"exp" 2021/10/05 Clarification. This is a technical expiration field, it means that the object cannot be processed after the expiration date. It does not reflect the validity of the data contained in the object, if any.
"nbf"

Alastria Identity Recovery payload example:

{
  "@context": ["https://alastria.github.io/identity/artifacts/v1"],
  "type": ["AlastriaIdentityRecovery","US31"],
  "recoverAlastriaTX":"0xf9...",
  "alastriaToken":"ey...",
  "publicKey":"0x2e...",
  "jti": "ze298y42sba",
  "iat": 1587712763,
  "exp": 1563783392,
  "nbf": 1563783392
}

1. Alastria ID Creation Flows

US-1.2 Alastria ID Creation

UML diagram Used artifacts are Alastria Token and Alastria Identity Creation

US-1.3 Legacy Onboarding with Alastria ID

UML diagram It uses no artifacts

US-1.4 Alastria ID & Legacy ID Linking

US-1.4.1 Alastria ID & Legacy ID Linking

UML diagram Used artifact is Alastria Token

US-1.4.2 Legacy ID & Alastria ID Linking

UML diagram

2. Alastria ID Regular Use Flows

US-2.1 Alastria ID Authentication

US-2.1.1 Alastria ID Authentication

UML diagram

Used artifact are Alastria Token and Alastria Session

US-2-2 Credentials

Credentials status transitions

Credentials transitions source

US-2.2.1 Credential Issuance

UML diagram

It uses no artifacts

US-2.2.2 Credential Revocation

UML diagram

It uses no artifacts

US-2.2.3 Credential Query Status

UML diagram It uses no artifacts

US-2.2.4 Expiring Credential

Out of MVP Scope

US-2.2.5 Credential Request

UML diagram Out of MVP Scope

US-2-3 Presentations

Presentations status transitions

Presentations transitions source

US-2.3.1.1 Presentation Request

UML diagram

US-2.3.1.2 Present Presentation

UML diagram

It uses no artifacts

US-2.3.2 Withdraw Presentation

UML diagram

It uses no artifacts

US-2.3.3 Presentation Query Status

UML diagram

It uses no artifacts

US-2.3.4 Expiring Presentation

Out of MVP Scope

3. Alastria ID recovery Flows

US-3.1 Identity Recovery

UML diagram Uses AIR (Alastria Identity Recovery) artifact

4. Alastria ID end of life Flows

Out of MVP Scope

5. Subprocedures

5.1 TinyURL Subprocedure

A TinyURL will be used in those scenarios where the JWT token would be too big to show as a QR code / deeplink. In Alastria this corresponds to the following user stories:

In these cases, the wallet will receive an Alastria Token (AT) from the entity. Once the wallet has verified the AT, it will need to sign and send an Alastria Session (AS) to the specific entity’s endpoint defined by the CBU parameter inside the AT.

Once the entity verifies and validates the AS, it will send the wallet a JSON with the required credentials or presentation request.

(Link to the UML diagram) alastria_tiny_url_v1

The JSON response schema sent by the entity depends on the user story:

2.2.1 Credential Issuance:

 {
    "verifiableCredential":[
       "eyJ0eXAgs...",
       "eyJ2c3Rga...",
       (…)
    ]
 }

The JSON contains a list of verifiableCredentials. This is defined in 3.4 Multiple Credentials

2.3.1.1 Presentation Request:

{
   “presentationRequest":[
      "eyJ0eXA...",
      (…)
    ]
}

The JSON contains the JWT with the presentation request.

5.2 Deeplink Subprocedure

A deeplink is utilized in situations where there is a requirement to transmit a JWT (JSON Web Token) and employing a QR code is not feasible. One such example is when a mobile application intends to send a JWT to a wallet located within the same device. Deep links have been defined for all of Alastria's US:

Create AlastriaID:

The create Alastria ID deeplink will have the following structure:

walletapp://alastria.com/createAI?alastriaToken=