代表用户获取访问权限Get access on behalf of a user

若要代表用户使用 Microsoft Graph 读取和写入资源,应用必须从 Microsoft 标识平台获取访问令牌,并将令牌附加到其发往 Microsoft Graph 的请求。你将用于获取访问令牌的确切的身份验证流会依赖于你正在开发的应用类型以及你是否要使用 OpenID Connect 让用户登录到应用中。本机和移动应用还有某些 Web 应用使用的常见流程就是 OAuth 2.0 授权代码授予流程。本主题将介绍一个使用此流程的示例。To use Microsoft Graph to read and write resources on behalf of a user, your app must get an access token from Azure AD and attach the token to requests that it sends to Microsoft Graph. The exact authentication flow that you will use to get access tokens will depend on the kind of app you are developing and whether you want to use OpenID Connect to sign the user in to your app. One common flow used by native and mobile apps and also by some Web apps is the OAuth 2.0 authorization code grant flow. In this topic, we will walk through an example using this flow.

身份验证和授权步骤Authentication and Authorization steps

需要执行下述基本步骤来使用 OAuth 2.0 授权代码授予流从 Microsoft 标识平台终结点获取访问令牌:The basic steps required to use the OAuth 2.0 authorization code grant flow to get an access token from the Microsoft identity platform endpoint are:

  1. 使用 Azure AD 注册应用。Register your app with Azure AD.
  2. 获取授权。Get authorization.
  3. 获取访问令牌。Get an access token.
  4. 使用访问令牌调用 Microsoft Graph。Call Microsoft Graph with the access token.
  5. 使用刷新令牌获取新的访问令牌。Use a refresh token to get a new access token.

1.注册你的应用程序1. Register your app

要使用 Microsoft 标识平台终结点,必须通过应用注册门户注册应用。可使用 Microsoft 帐户或工作/学校帐户来注册应用。To use the Microsoft identity platform endpoint, you must register your app using the Azure app registration portal. You can use either a Microsoft account or a work or school account to register an app.

若要配置应用以使用 OAuth 2.0 授权代码授予流程,将需要在注册应用时保存下列值:To configure an app to use the OAuth 2.0 authorization code grant flow, you'll need to save the following values when registering the app:

  • 应用注册门户分配的应用程序(客户端)ID。The Application ID assigned by the app registration portal.
  • 客户端(应用程序)密码,它是一个密码或是一个公钥/私钥对(证书)。A Client (application) Secret, either a password or a public/private key pair (certificate). 这不是本机应用的必需项。This is not required for native apps.
  • 可让应用接收来自 Azure AD 的响应的重定向 URL(或回复 URL)。A Redirect URL for your app to receive responses from Azure AD.

要分步了解如何在 Azure 门户中配置应用,请参阅注册应用For steps on how to configure an app in the Azure portal, see Register your app.

2. 获取授权2. Get authorization

首先是从多个 OpenID Connect 获取访问令牌,然后 OAuth 2.0 流会将用户重定向到 Microsoft 标识平台 /authorize 终结点。The first step to getting an access token for many OpenID Connect and OAuth 2.0 flows is to redirect the user to the Microsoft identity platform /authorize endpoint. Azure AD 将允许用户登录并确保其同意应用请求的权限。Azure AD will sign the user in and ensure their consent for the permissions your app requests. 在授权代码授予流中,获得同意后,Azure AD 将向你的应用返回一个授权代码,它可在 Microsoft 标识平台 /token 终结点处兑换访问令牌。In the authorization code grant flow, after consent is obtained, Azure AD will return an authorization_code to your app that it can redeem at the Microsoft identity platform /token endpoint for an access token.

授权请求Authorization request

以下示例显示了对 /authorize 终结点的请求示例。The following shows an example request to the /authorize endpoint.

借助 Microsoft 标识平台终结点,通过 scope 参数请求权限。With the Microsoft identity platform endpoint, permissions are requested using the scope parameter. 在本例中,所请求的 Microsoft Graph 权限可用于 User.ReadMail.Read,从而让应用能够读取已登录用户的个人资料和邮件。In this example, the Microsoft Graph permissions requested are for User.Read and Mail.Read, which will allow the app to read the profile and mail of the signed-in user. 已请求_脱机_访问_权限,这样应用就可获取刷新令牌,后者可用于在当前访问令牌过期时获取新的令牌。The offline_access permission is requested so that the app can get a refresh token, which it can use to get a new access token when the current one expires.

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=offline_access%20user.read%20mail.read
&state=12345
参数Parameter 说明Description
租户tenant 必需required 请求路径中的 {tenant} 值可用于控制登录应用程序的用户。允许的值为适用于 Microsoft 帐户和工作或学校帐户的 common、仅适用于工作或学校帐户的 organizations、仅适用于 Microsoft 帐户的 consumers 以及租户标识符(如租户 ID 或域名)。有关详细信息,请参阅协议基础The {tenant} value in the path of the request can be used to control who can sign into the application. The allowed values are common for both Microsoft accounts and work or school accounts, organizations for work or school accounts only, consumers for Microsoft accounts only, and tenant identifiers such as the tenant ID or domain name. For more detail, see protocol basics.
client_idclient_id 必需required 注册门户分配给应用的应用程序 ID。The Application ID that the registration portal assigned your app.
response_typeresponse_type 必需required 必须包括授权代码流的 codeMust include code for the authorization code flow.
redirect_uriredirect_uri 建议recommended 你的应用的 redirect_uri,你可以在其中通过应用发送并接收身份验证响应。它必须完全匹配你在应用注册门户中注册的 redirect_uris 之一,除了它必须采用 URL 编码。对于本机和移动应用,应使用默认值 https://login.microsoftonline.com/common/oauth2/nativeclientThe redirect_uri of your app, where authentication responses can be sent and received by your app. It must exactly match one of the redirect_uris you registered in the app registration portal, except it must be URL encoded. For native and mobile apps, you should use the default value of https://login.microsoftonline.com/common/oauth2/nativeclient.
范围scope 必需required 由空格分隔的希望用户同意的 Microsoft Graph 权限列表。这还可能包括 OpenID 范围。A space-separated list of the Microsoft Graph permissions that you want the user to consent to. This may also include OpenID scopes.
response_moderesponse_mode 建议recommended 指定用于将结果令牌发送回应用的方法。可以是 queryform_postSpecifies the method that should be used to send the resulting token back to your app. Can be query or form_post.
状态state 建议recommended 请求中包含的值将在令牌响应中返回。它可以是你希望的任何内容的字符串。随机生成的唯一值通常用于防止跨网站请求伪造攻击。此状态还用于在发生身份验证请求前,对应用中的用户状态信息进行编码(如它们所在的页面或视图上)。A value included in the request that will also be returned in the token response. It can be a string of any content that you wish. A randomly generated unique value is typically used for preventing cross-site request forgery attacks. The state is also used to encode information about the user's state in the app before the authentication request occurred, such as the page or view they were on.

重要说明:Microsoft Graph 公开两种类型的权限:应用程序性权限和委派权限。对于已登录用户运行的应用,在 scope 参数中请求委派权限。这些权限将已登录用户的特权委派给应用,允许其代表已登录的用户来调用 Microsoft Graph。有关可通过 Microsoft Graph 使用的权限的详细信息,请参阅权限引用Important: Microsoft Graph exposes two kinds of permissions: application and delegated. For apps that run with a signed-in user, you request delegated permissions in the scope parameter. These permissions delegate the privileges of the signed-in user to your app, allowing it to act as the signed-in user when making calls to Microsoft Graph. For more detailed information about the permissions available through Microsoft Graph, see the Permissions reference.

此时,用户将需要输入其凭据才能向 Microsoft 进行身份验证。At this point, the user will be asked to enter their credentials to authenticate with Microsoft. Microsoft 标识平台 v2.0 终结点还将确保用户已同意 scope 查询参数中指示的权限。The v2.0 endpoint will also ensure that the user has consented to the permissions indicated in the scope query parameter. 如果用户未同意上述任何权限,以及管理员之前未代表组织中的所有用户授予同意,则他们需要同意所需权限。If the user has not consented to any of those permissions and if an administrator has not previously consented on behalf of all users in the organization, they will be asked to consent to the required permissions.

下面是为 Microsoft 帐户用户呈现的同意对话框示例。Here is an example of the consent dialog presented for a Microsoft account:

Microsoft 帐户的同意对话框

试一试 如果你拥有 Microsoft 帐户或 Azure AD 工作或学校帐户,可以通过点击以下链接进行尝试:登录后,浏览器应被重定向到地址栏中有 codehttps://localhost/myapp/Try If you have a Microsoft account or an Azure AD work or school account, you can try this for yourself by clicking on the link below. After signing in, your browser should be redirected to https://localhost/myapp/ with a code in the address bar.

https://login.microsoftonline.com/common/oauth2/v2.0/authorize...https://login.microsoftonline.com/common/oauth2/v2.0/authorize...

授权响应Authorization response

如果用户同意应用请求的权限,响应将在 code 参数中提供授权代码。这是对上述请求的成功响应的示例。因为请求中的 response_mode 参数已设为 query,响应会在重定向 URL 的查询字符串中返回。If the user consents to the permissions your app requested, the response will contain the authorization code in the code parameter. Here is an example of a successful response to the request above. Because the response_mode parameter in the request was set to query, the response is returned in the query string of the redirect URL.

GET https://localhost/myapp/?
code=M0ab92efe-b6fd-df08-87dc-2c6500a7f84d
&state=12345
参数Parameter 说明Description
codecode 应用请求的 authorization_code。应用可以使用授权代码请求目标资源的访问令牌。Authorization_codes 有效期非常短暂,通常它们会在 10 分钟后失效。The authorization_code that the app requested. The app can use the authorization code to request an access token for the target resource. Authorization_codes are very short lived, typically they expire after about 10 minutes.
状态state 如果请求中包含状态参数,则应在响应中显示相同的值。应用应确认请求和响应中的状态值相同。If a state parameter is included in the request, the same value should appear in the response. The app should verify that the state values in the request and response are identical.

3.获取令牌3. Get a token

你的应用使用上一步接收的授权 code,通过发送 POST 请求到 /token 终结点来请求访问令牌。Your app uses the authorization code received in the previous step to request an access token by sending a POST request to the /token endpoint.

令牌请求Token request

// Line breaks for legibility only

POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&scope=user.read%20mail.read
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only required for web apps
参数Parameter 说明Description
租户tenant 必需required 请求路径中的 {tenant} 值可用于控制登录应用程序的用户。允许的值为适用于 Microsoft 帐户和工作或学校帐户的 common、仅适用于工作或学校帐户的 organizations、仅适用于 Microsoft 帐户的 consumers 以及租户标识符(如租户 ID 或域名)。有关详细信息,请参阅协议基础The {tenant} value in the path of the request can be used to control who can sign into the application. The allowed values are common for both Microsoft accounts and work or school accounts, organizations for work or school accounts only, consumers for Microsoft accounts only, and tenant identifiers such as the tenant ID or domain name. For more detail, see protocol basics.
client_idclient_id 必需required 注册门户分配给应用的应用程序 ID。The Application ID that the registration portal) assigned your app.
grant_typegrant_type 必需required 对于授权代码流必须为 authorization_codeMust be authorization_code for the authorization code flow.
范围scope 必需required 用空格分隔的范围列表。在此图例中请求的范围必须等于在首个(授权)图例中请求的范围或其子集。如果此请求中指定的范围跨越多个资源服务器,则 v2.0 将为首个范围中指定的资源返回令牌。A space-separated list of scopes. The scopes requested in this leg must be equivalent to or a subset of the scopes requested in the first (authorization) leg. If the scopes specified in this request span multiple resource servers, then the v2.0 endpoint will return a token for the resource specified in the first scope.
codecode 必需required 你在流程的第一个图例中获得的 authorization_code。The authorization_code that you acquired in the first leg of the flow.
redirect_uriredirect_uri 必需required 用于获取 authorization_code 的相同的 redirect_uri 值。The same redirect_uri value that was used to acquire the authorization_code.
client_secretclient_secret Web 应用需要required for web apps 你在应用注册门户中为应用创建的应用程序密码。它不可在本机应用中使用,因为设备无法可靠地存储 client_secrets。Web 应用和 Web API 需要此值,它们能够将 client_secret 安全地存储在服务器端上。The application secret that you created in the app registration portal for your app. It should not be used in a native app, because client_secrets cannot be reliably stored on devices. It is required for web apps and web APIs, which have the ability to store the client_secret securely on the server side.

令牌响应Token response

尽管访问令牌对应用是不透明的,但是响应包含了权限列表,访问令牌对 scope 参数中的这些权限有益。Although the access token is opaque to your app, the response contains a list of the permissions that the access token is good for in the scope parameter.

{
    "token_type": "Bearer",
    "scope": "user.read%20Fmail.read",
    "expires_in": 3600,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4..."
}
参数Parameter 说明Description
token_typetoken_type 表示令牌类型值。Azure AD 唯一支持的类型是 Bearer。Indicates the token type value. The only type that Azure AD supports is Bearer
范围scope 此 access_token 适用的空格分隔的 Microsoft Graph 权限列表。A space separated list of the Microsoft Graph permissions that the access_token is valid for.
expires_inexpires_in 访问令牌的有效期是多久(以秒为单位)。How long the access token is valid (in seconds).
access_tokenaccess_token 请求的访问令牌。你的应用可以使用此令牌调用 Microsoft Graph。The requested access token. Your app can use this token to call Microsoft Graph.
refresh_tokenrefresh_token OAuth 2.0 刷新令牌。An OAuth 2.0 refresh token. 在当前访问令牌到期后,应用程序可以使用此令牌获取其他访问令牌。Your app can use this token to acquire additional access tokens after the current access token expires. 刷新令牌有效期较长,可用于长时间保留对资源的访问权限。Refresh tokens are long-lived, and can be used to retain access to resources for extended periods of time. 有关详细信息,请参阅 v2.0 令牌参考For more detail, refer to the v2.0 token reference.

4. 使用访问令牌调用 Microsoft Graph4. Use the access token to call Microsoft Graph

拥有访问令牌后,可通过将其包含在请求的 Authorization 标头中,用其调用 Microsoft Graph。以下请求可获取已登录用户的个人资料。Once you have an access token, you can use it to call Microsoft Graph by including it in the Authorization header of a request. The following request gets the profile of the signed-in user.

GET https://graph.microsoft.com/v1.0/me 
Authorization: Bearer eyJ0eXAiO ... 0X2tnSQLEANnSPHY0gKcgw
Host: graph.microsoft.com

成功的响应将与下述内容类似(一些响应标头已被删除)。A successful response will look similar to this (some response headers have been removed):

HTTP/1.1 200 OK
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8
request-id: f45d08c0-6901-473a-90f5-7867287de97f
client-request-id: f45d08c0-6901-473a-90f5-7867287de97f
OData-Version: 4.0
Duration: 727.0022
Date: Thu, 20 Apr 2017 05:21:18 GMT
Content-Length: 407

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users/$entity",
    "id":"12345678-73a6-4952-a53a-e9916737ff7f",
    "businessPhones":[
        "+1 555555555"
    ],
    "displayName":"Chris Green",
    "givenName":"Chris",
    "jobTitle":"Software Engineer",
    "mail":null,
    "mobilePhone":"+1 5555555555",
    "officeLocation":"Seattle Office",
    "preferredLanguage":null,
    "surname":"Green",
    "userPrincipalName":"ChrisG@contoso.onmicrosoft.com"
}

5.使用此刷新令牌获取新的访问令牌。5. Use the refresh token to get a new access token

访问令牌有效期非常短暂,在过期后继续访问资源,必须进行刷新。你可以通过向 /token 终结点提交其他 POST 请求执行此操作,这时提交的是 refresh_token 而非 codeAccess tokens are short lived, and you must refresh them after they expire to continue accessing resources. You can do so by submitting another POST request to the /token endpoint, this time providing the refresh_token instead of the code.

请求Request

// Line breaks for legibility only

POST /common/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=6731de76-14a6-49ae-97bc-6eba6914391e
&scope=user.read%20mail.read
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=refresh_token
&client_secret=JqQX2PNo9bpM0uEihUPzyrh      // NOTE: Only required for web apps
参数Parameter 说明Description
client_idclient_id 必需required 注册门户分配给应用的应用程序 ID。The Application ID that the registration portal assigned your app.
grant_typegrant_type 必需required 必须是 refresh_tokenMust be refresh_token.
范围scope 必需required 用空格分隔的权限列表(范围)。请求的权限必须等于初始 authorization_code 请求中所请求的权限或其子集。A space-separated list of permissions (scopes). The permissions requested must be equivalent to or a subset of the permissions requested in the original authorization_code request.
refresh_tokenrefresh_token 必需required 令牌请求期间获得的 refresh_token。The refresh_token that you acquired during the token request.
redirect_uriredirect_uri 必需required 用于获取 authorization_code 的相同的 redirect_uri 值。The same redirect_uri value that was used to acquire the authorization_code.
client_secretclient_secret Web 应用需要required for web apps 你在应用注册门户中为应用创建的应用程序密码。它不可在本机应用中使用,因为设备无法可靠地存储 client_secrets。Web 应用和 Web API 需要此值,它们能够将 client_secret 安全地存储在服务器端上。The application secret that you created in the app registration portal for your app. It should not be used in a native app, because client_secrets cannot be reliably stored on devices. It is required for web apps and web APIs, which have the ability to store the client_secret securely on the server side.

响应Response

成功的令牌响将与下列内容类似。A successful token response will look similar to the following.

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "user.read%20mail.read",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4...",
}
参数Parameter 说明Description
access_tokenaccess_token 请求的访问令牌。应用可使用此令牌调用 Microsoft Graph。The requested access token. The app can use this token in calls to Microsoft Graph.
token_typetoken_type 表示令牌类型值。Azure AD 唯一支持的类型是 BearerIndicates the token type value. The only type that Azure AD supports is Bearer
expires_inexpires_in 访问令牌的有效期是多久(以秒为单位)。How long the access token is valid (in seconds).
范围scope access_token 适用的权限(范围)。The permissions (scopes) that the access_token is valid for.
refresh_tokenrefresh_token 新的 OAuth 2.0 刷新令牌。应当使用刚获得的刷新令牌替换旧的刷新令牌,尽可能确保你的刷新令牌仍旧有效。A new OAuth 2.0 refresh token. You should replace the old refresh token with this newly acquired refresh token to ensure your refresh tokens remain valid for as long as possible.

受支持的应用场景和其他资源Supported app scenarios and additional resources

你可以代表用户从以下类型的应用中调用 Microsoft Graph:You can call Microsoft Graph on behalf of a user from the following kinds of apps:

  • 本机/移动应用Native/Mobile apps
  • Web 应用Web apps
  • 单页应用 (SPA)Single page apps (SPA)
  • 后端 Web API:例如,在本机应用等客户端应用在 Web API 后端实现功能的情况下。Back-end Web APIs: For example, in scenarios where a client app, like a native app, implements functionality in a Web API back end. 通过 Microsoft 标识平台终结点,客户端应用和后端 Web API 必须具有相同的应用程序 ID。With the Microsoft identity platform endpoint, both the client app and the back-end Web API must have the same Application ID.

要详细了解 Microsoft 标识平台终结点支持的应用方案,请参阅应用方案和身份验证流程For more information about supported app scenarios with the Microsoft identity platform endpoint, see App scenarios and authentication flows.

请注意:Microsoft 标识平台终结点当前不支持通过独立的 Web API 调用 Microsoft Graph。Note: Calling Microsoft Graph from a standalone web API is not currently supported by the Microsoft identity platform endpoint. 在此情况下,需要使用 Azure AD 终结点。For this scenario, you need to use the Azure AD endpoint.

若要详细了解如何代表用户从 Microsoft标识平台终结点获取访问 Microsoft Graph 的权限:For more information about getting access to Microsoft Graph on behalf of a user from the Microsoft identity platform endpoint:

终结点注意事项Endpoint considerations

Microsoft 继续支持 Azure AD 终结点。Microsoft continues to support the Azure AD endpoint. 在使用 Microsoft 标识平台终结点和使用 Azure AD 终结点之间存在诸多区别There are several differences between using the Microsoft identity platform endpoint and the Azure AD endpoint. 使用 Azure AD 终结点时:When using the Azure AD endpoint:

  • 应用将需要为每个平台提供不同的应用程序 ID(客户端 ID)。Your app will require a different application ID (client ID) for each platform.
  • 如果应用为多租户应用,则必须在 Azure 门户中通过显式方式将其配置为多租户。If your app is a multi-tenant app, you must explicitly configure it to be multi-tenant at the Azure portal.
  • 应用必需的所有权限都必须由开发人员进行配置。All permissions that your app needs must be configured by the developer. Azure AD 终结点不支持动态(增量)同意。The Azure AD endpoint does not support dynamic (incremental) consent.
  • Azure AD 终结点使用授权中的 resource 参数和令牌请求,指定其需要权限的资源(如 Microsoft Graph)。终结点不支持 scope 参数。The Azure AD endpoint uses a resource parameter in authorization and token requests to specify the resource, such as Microsoft Graph, for which it wants permissions. The endpoint does not support the scope parameter.
  • Azure AD 终结点不会公开管理员同意的特定终结点。反之,应用会使用授权请求中的 prompt=admin_consent 参数,为组织获取管理员同意。有关详细信息,请参阅将应用程序与 Azure Active Directory 相集成中的在运行时引发 Azure AD 同意框架The Azure AD endpoint does not expose a specific endpoint for administrator consent. Instead apps use the prompt=admin_consent parameter in the authorization request to obtain administrator consent for an organization. For more information, see Triggering the Azure AD consent framework at runtime in Integrating applications with Azure Active Directory.

有关代表用户从 Azure AD 终结点获取对 Microsoft Graph 访问的详细信息:For more information about getting access to Microsoft Graph on behalf of a user from the Azure AD endpoint:

  • 要了解如何将 Microsoft 标识平台终结点与不同类型的应用结合使用,请参阅 Microsoft 标识平台开发人员文档中的开始使用链接。For information about using the Microsoft identity platform endpoint with different kinds of apps, see the Get Started links in the Microsoft identity platform developer documentation. 该文档包含众多链接,可通过它们查看 Microsoft 标识平台终结点支持的不同类型的应用的概述主题、快速入门、教程、代码示例和协议文档。The documentation contains links to overview topics, quickstarts, tutorials, code samples and protocol documentation for different kinds of apps supported by the Microsoft identity platform endpoint.
  • 要了解可与 Microsoft 标识平台终结点结合使用的 Microsoft 身份验证库 (MSAL) 和服务器中间件,请参阅 Microsoft 身份验证库For information about the Microsoft Authentication Library (MSAL) and server middleware available for use with the Microsoft identity platform endpoint, see Microsoft Authentication Libraries.