logo

Extra Properties

Table of Contents

1. Visão geral

Propriedades arbitrárias podem ser associadas a um token de acesso.

Aqui propriedade é um objeto JSON que tem entradas nomeadas key e value. Os tipos dos valores de entrada são string. Literalmente key representa a chave da propriedade e value representa o valor da propriedade.

O JSON abaixo é um exemplo de uma propriedade cuja chave e valor são example_parameter e example_valuerespectivamente.

{
    "key":"example_parameter",
    "value":"example_value"
}

Por exemplo, se a propriedade acima estiver associada a um token de acesso, uma resposta de token de acesso do seu servidor de autorização será semelhante aos exemplos abaixo.

Exemplo em Fluxo Implícito

Location: http://localhost:8880/api/mock/redirection/5593494639
    #access_token=pNj1h24a4geA_YHilxrshkRkxJDsyXBZWKp3hZ5ND7A
    &token_type=Bearer&expires_in=86400&scope=
    &example_parameter=example_value

Exemplo no Fluxo de Código de Autorização

{
    "access_token":"pNj1h24a4geA_YHilxrshkRkxJDsyXBZWKp3hZ5ND7A",
    "token_type":"Bearer",
    "expires_in":86400,
    "scope":null,
    "example_parameter":"example_value"
}

Como você pode ver, uma propriedade, example_parameter=example_value, está incluído no redirecionamento URI em “Exemplo em Fluxo Implícito” e no JSON em “Exemplo no Fluxo de Código de Autorização”. O imóvel é passado para a solicitação do cliente. No entanto, pode haver alguns casos em que você deseja associar propriedades a um token de acesso, mas não quer mostrá-las ao aplicativo do cliente. Nesse caso, adicione hidden=true Como abaixo quando você prepara uma propriedade.

{
    "key":"example_parameter",
    "value":"example_value",
    "hidden":true
}

As propriedades associadas a um token de acesso podem ser obtidas usando a API /api/auth/introspection API (que é a API para obter informações sobre um token de acesso). Uma resposta da API de introspecção contém propriedades associadas no formato como mostrado abaixo.

{
    "type":"introspectionResponse",
    "resultCode":"A056001",
    "resultMessage":"[A056001] The access token is valid.",
    "action":"OK",
    "clientId":5008706718,
    "existent":true,
    "expiresAt":1461369117000,
    "properties":[
        {
            "hidden":false,
            "key":"example_parameter",
            "value":"example_value"
        }
    ],
    "refreshable":false,
    "responseContent":"Bearer error=\"invalid_request\"",
    "subject":"user123",
    "sufficient":true,
    "usable":true
}

Observe que a resposta da API de introspecção da Authlete é diferente do formato definido em RFC 7662 Ver 4. Token de acesso introspect em Authlete Definitivo Guia para detalhes.

2. Restrição

  1. As chaves listadas abaixo não podem ser usadas como chaves de propriedade. Eles são ignorados no lado do servidor, mesmo que dado. A razão é que eles estão reservados em RFC 6749 e OpenID Connect Core 1.0 como nomes de parâmetros usados em respostas de um servidor de autorização.
    • access_token
    • token_type
    • expires_in
    • refresh_token
    • âmbito
    • erro
    • error_description
    • error_uri
    • id_token
  2. O único tipo de valor de propriedade permitido é string. Boolean, array e outros tipos não podem ser usados.
  3. Há uma limitação de comprimento. As propriedades são salvas no banco de dados do lado do rio seram depois de passar pelas etapas descritas abaixo.
    • Convertido em uma matriz bidimensional (por exemplo. [["example_parameter","example_value",null]]). O valor do oculto é convertido em uma sequência nula ou vazia. Significam falsos e verdadeiros, respectivamente.
    • Convertido em JSON (por exemplo. "[[\"example_parameter\":\"example_value\",null]]")
    • Criptografado por AES/CBC/PKCS5Padding
    • Codificado por base64url
    • Se o comprimento da sequência base64url resultante gerada pelas etapas acima exceder 65535, ocorrer um erro.

3. Como simular o fluxo implícito usando curl

  1. Passe uma solicitação de um cliente para um ponto final de autorização, "client_id=5008706718&response_type=token"Para /auth/authorization API.

    curl -s -v \
--user 5593494639:AAw0rner_-y1A6J9s20wjRCpkBvez3GxEBoL9jOJVR0 \
http://localhost:8880/api/auth/authorization \
-d "parameters=client_id%3D5008706718%26response_type%3Dtoken"

    Extrair o valor de ticket da longa resposta JSON. O ticket é usado para chamar /auth/authorization/issue API mais tarde.

  2. Emita um token de acesso ligando /auth/authorization/issue API. Aqui, especifique propriedades para associar a um token de acesso usando properties parâmetro.

    curl -s -v \
--user 5593494639:AAw0rner_-y1A6J9s20wjRCpkBvez3GxEBoL9jOJVR0 \
http://localhost:8880/api/auth/authorization/issue \
-H 'Content-Type:application/json' \
-d "{\"ticket\":\"1iIR-GMmBLLQLC-tJ70Wmb83UKAB2V8WnhwsVWlGJr8\",\"subject\":\"user123\",\"properties\":[{\"key\":\"example_parameter\",\"value\":\"example_value\"}]}"

    Uma resposta JSON como abaixo é devolvida.

    {
    "type":"authorizationIssueResponse",
    "resultCode":"A040001",
    "resultMessage":"[A040001] The authorization request was processed successfully.",
    "action":"LOCATION",
    "responseContent":"http://localhost:8880/api/mock/redirection/5593494639#access_token=pNj1h24a4geA_YHilxrshkRkxJDsyXBZWKp3hZ5ND7A&token_type=Bearer&expires_in=86400&scope=&example_parameter=example_value"
}

  3. Como o valor de action contido na resposta acima de /auth/autorização/emissão API é LOCATION, status HTTP “302 Encontrado” deve ser devolvido ao aplicativo do cliente. Quando o valor de action contido em uma resposta de /auth/autorização/emissão API é LOCATION, o valor de responseContent é o valor que deve ser usado como o valor do cabeçalho LOCAL HTTP. Usando essas informações, uma resposta como abaixo deve ser devolvida ao aplicativo do cliente.

    HTTP/1.1 302 Found
Location: http://localhost:8880/api/mock/redirection/5593494639
    #access_token=pNj1h24a4geA_YHilxrshkRkxJDsyXBZWKp3hZ5ND7A
    &token_type=Bearer&expires_in=86400&scope=
    &example_parameter=example_value
Cache-Control: no-store
Pragma: no-cache

    Observe que esta resposta contém example_parameter=example_value como um parâmetro adicional.

  4. Informações sobre o token de acesso emitido podem ser obtidas ligando para a API/AUTH/Introspection API abaixo.

    curl -s -v \
--user 5593494639:AAw0rner_-y1A6J9s20wjRCpkBvez3GxEBoL9jOJVR0 \
http://localhost:8880/api/auth/introspection \
-d token=pNj1h24a4geA_YHilxrshkRkxJDsyXBZWKp3hZ5ND7A

    Abaixo está um exemplo da API de introspecção.

    {
    "type":"introspectionResponse",
    "resultCode":"A056001",
    "resultMessage":"[A056001] The access token is valid.",
    "action":"OK",
    "clientId":5008706718,
    "existent":true,
    "expiresAt":1461369117000,
    "properties":[
        {
            "hidden":false,
            "key":"example_parameter",
            "value":"example_value"
        }
    ],
    "refreshable":false,
    "responseContent":"Bearer error=\"invalid_request\"",
    "subject":"user123",
    "sufficient":true,
    "usable":true
}

4. Como simular o fluxo do código de autorização usando curl

  1. Passe uma solicitação de um cliente para um ponto final de autorização, "client_id=5008706718&response_type=code"Para /auth/authorization API.

    curl -s -v \
--user 5593494639:AAw0rner_-y1A6J9s20wjRCpkBvez3GxEBoL9jOJVR0 \
http://localhost:8880/api/auth/authorization \
-d "parameters=client_id%3D5008706718%26response_type%3Dcode"

    Extrair o valor de ticket da longa resposta JSON. O ticket é usado para chamar /auth/authorization/issue API mais tarde.

  2. Emita um código de autorização ligando /auth/authorization/issue API. Aqui, especifique propriedades para associar a um código de autorização usando o parâmetro de propriedades. As propriedades especificadas serão finalmente associadas a um token de acesso. Observe que propriedades adicionais podem ser passadas para /auth/token API que será chamada mais tarde, também. Portanto, no fluxo de código de autorização, as propriedades não necessariamente têm que ser dadas a /auth/authorization/issue API mesmo que as propriedades precisem ser associadas a um token de acesso.

    curl -s -v \
--user 5593494639:AAw0rner_-y1A6J9s20wjRCpkBvez3GxEBoL9jOJVR0 \
http://localhost:8880/api/auth/authorization/issue \
-H 'Content-Type:application/json' \
-d "{\"ticket\":\"xKdGvPyPkLJRkmP6MSAJ1wISBmdnSbPG8pFzgTdZh4U\",\"subject\":\"user123\",\"properties\":[{\"key\":\"example_parameter\",\"value\":\"example_value\"}]}"

    Um JSON como abaixo é devolvido.

    {
    "type":"authorizationIssueResponse",
    "resultCode":"A040001",
    "resultMessage":"[A040001] The authorization request was processed successfully.",
    "action":"LOCATION",
    "responseContent":"http://localhost:8880/api/mock/redirection/5593494639?code=n96DtM32eV8maSG5Z3_p3qhAT7zuvuqlAaizOmDInZ4"
}

  3. Como o valor de action contido na resposta acima de /auth/authorization/issue API é LOCATION, status HTTP “302 Encontrado” deve ser devolvido ao aplicativo do cliente. Quando o valor de action contido em uma resposta de /auth/authorization/issue API é LOCATION, o valor de responseContent é o valor que deve ser usado como o valor do cabeçalho LOCAL HTTP. Usando essas informações, uma resposta como abaixo deve ser devolvida ao aplicativo do cliente.

    HTTP/1.1 302 Found
Location: http://localhost:8880/api/mock/redirection/5593494639?code=n96DtM32eV8maSG5Z3_p3qhAT7zuvuqlAaizOmDInZ4
Cache-Control: no-store
Pragma: no-cache

  4. Passe uma solicitação de um cliente para um ponto final de token, "code=n96DtM32eV8maSG5Z3_p3qhAT7zuvuqlAaizOmDInZ4&grant_type=authorization_code"Para /auth/token API. Observe que uma propriedade adicional para associar a um token de acesso, additional_parameter=additional_value, é especificado aqui. Se houver nomes de chaves duplicados em propriedades passadas para /auth/authorization/emissão de API e aqueles passados para /auth/token API, aqueles passados para /auth/token A API substituirá aqueles que passaram para /auth/authorization/issue API.

    curl -s -v \
--user 5593494639:AAw0rner_-y1A6J9s20wjRCpkBvez3GxEBoL9jOJVR0 \
http://localhost:8880/api/auth/token \
-H 'Content-Type:application/json' \
-d "{\"parameters\":\"code=n96DtM32eV8maSG5Z3_p3qhAT7zuvuqlAaizOmDInZ4&grant_type=authorization_code\",\"properties\":[{\"key\":\"additional_parameter\",\"value\":\"additional_value\"}]}"

    Um JSON como abaixo é devolvido.

    {
    "type":"tokenResponse",
    "resultCode":"A050001",
    "resultMessage":"[A050001] The token request (grant_type=authorization_code) was processed successfully.",
    "action":"OK",
    "responseContent":"{\"access_token\":\"xuc8cd1zf9TpdMwiB7sfLcPmY6DHpYIpz1jyo9a0YXs\",\"additional_parameter\":\"additional_value\",\"refresh_token\":\"66fIuQ33usvJ9ZSDrnUv2KQnC946Kr4Cj8n8bcjlpTI\",\"example_parameter\":\"example_value\",\"scope\":null,\"token_type\":\"Bearer\",\"expires_in\":86400}"
}

  5. Como o valor de action contido na resposta acima de /auth/token API é OK, o status HTTP “200 OK” deve ser devolvido ao aplicativo do cliente. Quando o valor de action contido em uma resposta de /auth/token API é OK, o valor de responseContent é o valor que deve ser usado como o valor do corpo de resposta. Usando essas informações, uma resposta como abaixo deve ser devolvida ao aplicativo do cliente.

    HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
    "access_token":"xuc8cd1zf9TpdMwiB7sfLcPmY6DHpYIpz1jyo9a0YXs",
    "additional_parameter":"additional_value",
    "refresh_token":"66fIuQ33usvJ9ZSDrnUv2KQnC946Kr4Cj8n8bcjlpTI",
    "example_parameter":"example_value",
    "scope":null,
    "token_type":"Bearer",
    "expires_in":86400
}

    Nesta resposta, a propriedade dada a /auth/authorization/issue API (example_parameter=example_value) e a propriedade dada a /auth/token API (additional_parameter=additional_value) estão contidos.

5. Como simular o fluxo de credenciais do cliente usando curl

  1. Passe uma solicitação de um cliente para um ponto final de token, grant_type=client_credentials&client_id=5008706718, para /api/auth/token API. Usar properties parâmetro para especificar propriedades para associar a um token de acesso. Observe que o tipo de cliente do aplicativo do cliente deve ser confidencial para usar o Fluxo de Credenciais do Cliente.

    curl -s -v \
--user 5593494639:AAw0rner_-y1A6J9s20wjRCpkBvez3GxEBoL9jOJVR0 \
http://localhost:8880/api/auth/token \
-H 'Content-Type:application/json' \
-d "{\"parameters\":\"grant_type=client_credentials&client_id=5008706718&client_secret=zVI5JjIKw4W2XIF7o8GLzaUOs4jAx_OhuWf7ol-lAMpMrzm574zmnhgzOTDApSHgUD4LKv41aD43p0gU4Hz67w\",\"properties\":[{\"key\":\"example_parameter\",\"value\":\"example_value\"}]}"

    Um JSON como abaixo é devolvido.

    {
    "type":"tokenResponse",
    "resultCode":"A052001",
    "resultMessage":"[A052001] The token request (grant_type=client_credentials) was processed successfully.",
    "action":"OK",
    "responseContent":"{\"access_token\":\"8PKs66MYc1nRVUcdE5wmEr3gn3lQ9FtcxRQWY3ts-fw\",\"example_parameter\":\"example_value\",\"scope\":null,\"token_type\":\"Bearer\",\"expires_in\":86400}"
}

    Como o valor de action contido na resposta acima da API/Auth/token é OK, o status HTTP “200 OK” deve ser devolvido ao aplicativo do cliente. Quando o valor de action contido em uma resposta de /api/auth/token API é OK, o valor de responseContent é o valor que deve ser usado como o valor do corpo de resposta. Usando essas informações, uma resposta como abaixo deve ser devolvida ao aplicativo do cliente.

    HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
    "access_token":"8PKs66MYc1nRVUcdE5wmEr3gn3lQ9FtcxRQWY3ts-fw",
    "example_parameter":"example_value",
    "scope":null,
    "token_type":"Bearer",
    "expires_in":86400
}

    No Fluxo de Credenciais do Cliente, um token de atualização (refresh_token) não é emitido. Ver RFC 6749 para detalhes.

6. Como simular o fluxo de credenciais de senha do proprietário do recurso usando curl

  1. Passe uma solicitação de um cliente para um ponto final de token, grant_type=password&client_id=5008706718&username=u&password=pPara /auth/token API. Quando grant_type É password, o valor do parâmetro de propriedades dado a /auth/token A API é simplesmente descartada. Então, não está especificado aqui. Em vez disso, o parâmetro de propriedades é usado mais tarde quando /auth/token/issue API é chamada. Note que /auth/token/issue A API existe apenas para grant_type=password.

    curl -s -v \
--user 5593494639:AAw0rner_-y1A6J9s20wjRCpkBvez3GxEBoL9jOJVR0 \
http://localhost:8880/api/auth/token \
-H 'Content-Type:application/json' \
-d "{\"parameters\":\"grant_type=password&client_id=5008706718&username=u&password=p\"}"

    Um JSON como abaixo é devolvido.

    {
    "type":"tokenResponse",
    "resultCode":"A051001",
    "resultMessage":"[A051001] Authlete has successfully issued a ticket to the service (API Key = 5593494639) for the token request from the client (ID = 5008706718). [grant_type=password]",
    "action":"PASSWORD",
    "password":"p",
    "ticket":"qdPziRKfjuHkaTbCQ5r0lBeR3pwJxCnEKrdPv5zbfRI",
    "username":"u"
}

  2. Quando o valor de action em uma resposta de /auth/token API é PASSWORD, isso significa que o Fluxo de Credenciais de Senha do Proprietário de Recursos está sendo usado. Neste caso, como primeiro passo, a autenticação do usuário precisa ser realizada usando username e password apresentado pelo aplicativo do cliente. Os valores de username parâmetro e password parâmetro na solicitação de token original estão contidos em uma resposta de /auth/token API sem qualquer modificação. No exemplo acima, o valor de username É u e o de password É p.

  3. Como resultado da autenticação do usuário, o identificador exclusivo do usuário deve ser determinado. Chamar /auth/token/issue API com o identificador único como o valor de subject parâmetro. Além disso, a chamada API requer ticket que foi emitido a partir de /auth/token API com antecedência. Se algumas propriedades precisarem ser associadas a um token de acesso, properties parâmetro de solicitação deve ser adicionado, também.

    curl -s -v \
--user 5593494639:AAw0rner_-y1A6J9s20wjRCpkBvez3GxEBoL9jOJVR0 \
http://localhost:8880/api/auth/token/issue \
-H 'Content-Type:application/json' \
-d "{\"ticket\":\"qdPziRKfjuHkaTbCQ5r0lBeR3pwJxCnEKrdPv5zbfRI\",\"subject\":\"user123\",\"properties\":[{\"key\":\"example_parameter\",\"value\":\"example_value\"}]}"

    Um JSON como abaixo é devolvido.

    {
    "type":"tokenIssueResponse",
    "resultCode":"A054001",
    "resultMessage":"[A054001] The token request (grant_type=password) was processed successfully.",
    "action":"OK",
    "responseContent":"{\"access_token\":\"jUmm2CSQGHb4OuUIGabdsqL1S0KNJWlZrP5lDNDEWX0\",\"refresh_token\":\"Q4OAafrltI5khG0Ur6c6XuJVQ1IU5Tjrk2sqD2sfKCo\",\"example_parameter\":\"example_value\",\"scope\":null,\"token_type\":\"Bearer\",\"expires_in\":86400}"
}

    Como o valor de action contido na resposta acima de /auth/token/issue API é OK, o status HTTP “200 OK” deve ser devolvido ao aplicativo do cliente. Quando o valor de action contido em uma resposta de /auth/token/issue API é OK, o valor de responseContent é o valor que deve ser usado como o valor do corpo de resposta. Usando essas informações, uma resposta como abaixo deve ser devolvida ao aplicativo do cliente.

    HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
    "access_token":"jUmm2CSQGHb4OuUIGabdsqL1S0KNJWlZrP5lDNDEWX0",
    "refresh_token":"Q4OAafrltI5khG0Ur6c6XuJVQ1IU5Tjrk2sqD2sfKCo",
    "example_parameter":"example_value",
    "scope":null,
    "token_type":"Bearer",
    "expires_in":86400
}

7. Como simular o fluxo de token de atualização usando curl

  1. Passe uma solicitação de um cliente para um ponto final de token, refresh_token=66fIuQ33usvJ9ZSDrnUv2KQnC946Kr4Cj8n8bcjlpTI&grant_type=refresh_tokenPara /auth/token API. As propriedades para associar a um token de acesso devem ser especificadas usando properties parâmetro. Neste exemplo, a propriedade é extra_parameter=extra_value e isso é um pouco diferente das propriedades de exemplo usadas até agora.

    curl -s -v \
--user 5593494639:AAw0rner_-y1A6J9s20wjRCpkBvez3GxEBoL9jOJVR0 \
http://localhost:8880/api/auth/token \
-H 'Content-Type:application/json' \
-d "{\"parameters\":\"refresh_token=66fIuQ33usvJ9ZSDrnUv2KQnC946Kr4Cj8n8bcjlpTI&grant_type=refresh_token\",\"properties\":[{\"key\":\"extra_parameter\",\"value\":\"extra_value\"}]}"

    Um JSON como abaixo é devolvido.

    {
    "type":"tokenResponse",
    "resultCode":"A053001",
    "resultMessage":"[A053001] The token request (grant_type=refresh_token) was processed successfully.",
    "action":"OK",
    "responseContent":"{\"access_token\":\"KQfuhsimWoOaTZVRYbzh166pqK49hQyNMGTbbN8UfUY\",\"additional_parameter\":\"additional_value\",\"refresh_token\":\"CdcL3Ixx5EIn2KK3ChDKUgoY_nf-1rHad7Z8Xk_O5s0\",\"example_parameter\":\"example_value\",\"extra_parameter\":\"extra_value\",\"scope\":null,\"token_type\":\"Bearer\",\"expires_in\":86400}"
}

    Quando grant_type É refresh_token, propriedades passadas para /auth/token As API são tratadas como propriedades adicionais para o token de acesso que é acoplado com o token de atualização apresentado. O valor de refresh_token parâmetro no exemplo acima é o token de atualização que foi emitido como resultado de “4. Como simular o fluxo de código de autorização por cacho”. E o token de acesso que está associado ao token de atualização já tem duas propriedades, example_parameter=example_value e additional_parameter=additional_value. Portanto, como resultado da adição extra_parameter=extra_value em /auth/token Chamada de API, um token de acesso recém-emitido terá três propriedades.

  2. Como o valor de action contido na resposta acima de /auth/token API é OK, o status HTTP “200 OK” deve ser devolvido ao aplicativo do cliente. Quando o valor de action contido em uma resposta de /auth/token API é OK, o valor de responseContent é o valor que deve ser usado como o valor do corpo de resposta. Usando essas informações, uma resposta como abaixo deve ser devolvida ao aplicativo do cliente.

    HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

{
    "access_token":"KQfuhsimWoOaTZVRYbzh166pqK49hQyNMGTbbN8UfUY",
    "additional_parameter":"additional_value",
    "refresh_token":"CdcL3Ixx5EIn2KK3ChDKUgoY_nf-1rHad7Z8Xk_O5s0",
    "example_parameter":"example_value",
    "extra_parameter":"extra_value",
    "scope":null,
    "token_type":"Bearer",
    "expires_in":86400
}

  3. Passando o token de acesso recém-emitido para a API de introspecção:

    curl -s -v \
--user 5593494639:AAw0rner_-y1A6J9s20wjRCpkBvez3GxEBoL9jOJVR0 \
http://localhost:8880/api/auth/introspection \
-d token=KQfuhsimWoOaTZVRYbzh166pqK49hQyNMGTbbN8UfUY

    resultará em uma resposta como abaixo. Três propriedades estão incorporadas na resposta.

    {
    "type":"introspectionResponse",
    "resultCode":"A056001",
    "resultMessage":"[A056001] The access token is valid.",
    "action":"OK",
    "clientId":5008706718,
    "existent":true,
    "expiresAt":1461519667000,
    "properties":[
        {
            "hidden":false,
            "key":"example_parameter",
            "value":"example_value"
        },
        {
            "hidden":false,
            "key":"additional_parameter",
            "value":"additional_value"
        },
        {
            "hidden":false,
            "key":"extra_parameter",
            "value":"extra_value"
        }
    ],
    "refreshable":true,
    "responseContent":"Bearer error=\"invalid_request\"",
    "subject":"user123",
    "sufficient":true,
    "usable":true
}