# `oidcc_userinfo`
[🔗](https://github.com/erlef/oidcc/blob/ee3434ddec86c14471af8f8a8f159971e654da3c
/src/oidcc_userinfo.erl#L4)

OpenID Connect Userinfo

See https://openid.net/specs/openid-connect-core-1_0.html#UserInfo

## Telemetry

See [`Oidcc.Userinfo`](`m:'Elixir.Oidcc.Userinfo'`).

# `error`
*since 3.0.0* 

```elixir
-type error() ::
          {distributed_claim_not_found, {ClaimSource :: binary(), ClaimName :: binary()}} |
          no_access_token | invalid_content_type | bad_subject |
          oidcc_jwt_util:error() |
          oidcc_http_util:error().
```

# `retrieve_opts`
*since 3.0.0* 

```elixir
-type retrieve_opts() ::
          #{refresh_jwks => oidcc_jwt_util:refresh_jwks_for_unknown_kid_fun(),
            expected_subject => binary() | any,
            dpop_nonce => binary()}.
```

Configure userinfo request

See https://openid.net/specs/openid-connect-core-1_0.html#UserInfoRequest

## Parameters

* `refresh_jwks` - How to handle tokens with an unknown `kid`.
  See `t:oidcc_jwt_util:refresh_jwks_for_unknown_kid_fun/0`
* `expected_subject` - expected subject for the userinfo
  (`sub` from id token)
* `dpop_nonce` - if using DPoP, the `nonce` value to use in the
    proof claim

# `retrieve_opts_no_sub`
*since 3.0.0* 

```elixir
-type retrieve_opts_no_sub() ::
          #{refresh_jwks => oidcc_jwt_util:refresh_jwks_for_unknown_kid_fun(), dpop_nonce => binary()}.
```

See `t:retrieve_opts/0`.

# `retrieve`
*since 3.0.0* 

```elixir
-spec retrieve(Token, ClientContext, Opts) -> {ok, oidcc_jwt_util:claims()} | {error, error()}
                  when
                      Token :: oidcc_token:t(),
                      ClientContext :: oidcc_client_context:t(),
                      Opts :: retrieve_opts_no_sub();
              (Token, ClientContext, Opts) -> {ok, oidcc_jwt_util:claims()} | {error, error()}
                  when
                      Token :: oidcc_token:access() | binary(),
                      ClientContext :: oidcc_client_context:t(),
                      Opts :: retrieve_opts().
```

Load userinfo for the given token

For a high level interface using `m:oidcc_provider_configuration_worker`, see
`oidcc:retrieve_userinfo/5`.

## Examples

```erlang
{ok, ClientContext} =
  oidcc_client_context:from_configuration_worker(provider_name,
                                                 <<"client_id">>,
                                                 <<"client_secret">>),

%% Get Token

{ok, #{<<"sub">> => Sub}} =
  oidcc_userinfo:retrieve(Token, ClientContext, #{}).
```

---

*Consult [api-reference.md](api-reference.md) for complete listing*