- 認可コードグラントタイプ(3-legged OAuth)の概要
- Indeedパートナーになる
- 認可コードを取得する
- OAuth認証情報を取得する
- 3-leggedアクセストークンを取得する
- 3-leggedアクセストークンを更新する
- Indeed APIを呼び出す
- 雇用主を表すアクセストークンを取得する
- Indeedの雇用主選択画面を表示する
- カスタム雇用主選択画面を表示する
- 雇用主アクセストークンを取得する
- ユーザー情報を取得する
- IDトークン
- userinfo エンドポイント
- ユーザーを複数のURLに動的にリダイレクトする
- ガイドライン
- 認可コードの漏洩を防ぐ
- リダイレクト URI にクエリパラメーターを付加しない
- 関連項目
認可コードグラントタイプ(3-legged OAuth)
Indeedのユーザーアカウントおよび関連付けられた雇用主アカウントに代わって動作することをアプリに認可します。
本 API および本ドキュメントを利用し、連携を構築することにより、Additional API Terms and Guidelines に同意したものとみなされます。
認可コードグラントタイプ(3-legged OAuth)の概要
認可コードグラントタイプ(3-legged OAuth)を使用して、Indeedのユーザーアカウントおよび関連付けられた雇用主アカウントに代わって動作することをアプリに認可します。
Indeed パートナーになると、Indeed が連携用のアプリを作成します。Partner Console にサインインして、アプリと OAuth 認証情報(クライアント ID、クライアントシークレット、および 3-legged OAuth の場合は認可コード)を確認します。認証情報をアクセストークンと交換し、API 呼び出しを認証します。
次のタスクも実行できます。
- 雇用主を表すアクセストークンを取得する。
- アプリを登録したユーザーアカウントの情報を取得する。
- ユーザーを複数のURLに動的にリダイレクトする。
- 認可コードの漏洩を防ぐ。
Indeedパートナーになる
まだパートナーでない場合は、Indeed パートナーになる をご覧ください。
認可コードを取得する
アプリは、3-legged OAuth認証情報(認可コード)をリクエストする必要があります。
認可コードフローを開始するには、IndeedのOAuth 2.0サーバーへのリクエストURLを作成し、email、offline_access、employer_accessの権限をユーザーに要求します。
ユーザーをその URL にリダイレクトします。Indeed は OAuth 同意画面を表示します。
ユーザーが Allow を選択すると、Indeed は認可コードを redirect_uri エンドポイントに送信し、code、iss、state のレスポンスフィールドを追加します。認可コードは 10 分で失効します。oauth/v2/authorize のレスポンスフィールドをご覧ください。
-
https://secure.indeed.com/oauth/v2/authorizeにある Indeed OAuth 2.0 サーバーへのリクエスト URL を作成します。次のリクエストURLの例では、
email、offline_access、employer_accessの権限をユーザーに要求しています。読みやすさのため、この例のURLには改行とスペースを含めています。
https://secure.indeed.com/oauth/v2/authorize?client_id=c4acac1b35917a14c11947f6564ee28a0758398cd0fdf4deec685c40f14bb8a8&redirect_uri=http%3A%2F%2Fwww.acerecruitersllc.com%2Foauth%2Findeed&response_type=code&scope=email+offline_access+employer_access&state=employer1234oauth/v2/authorizeのクエリパラメーターは次のとおりです。oauth/v2/authorizeのクエリパラメーター クエリパラメーター 必須 説明 client_id✔
クライアントID。
redirect_uri✔
URLエンコードされたリダイレクトURL。認可コードを取得するサイト内のリダイレクトページを指定します。アプリで登録したリダイレクトURLのいずれかと一致している必要があります。
response_type✔
常に
codeです。scope✔
クライアントアプリがリクエストする権限。スコープはURLエンコードしてスペース区切りで指定する必要があります(スペースはプラス記号(
+)に置き換えられます)。この例では、
email、offline_access、employer_accessの権限をユーザーに要求しています。state推奨
CSRF攻撃を防止します。リクエストとコールバックの間で状態を保持するためにアプリが生成する一意の文字列を指定できます。IndeedはこのパラメーターをリダイレクトURIに渡します。
-
ユーザーをリクエストURLにリダイレクトします。
Indeed は、アクセスしたいアカウントを持つユーザーに OAuth 同意画面を表示します。
ユーザーが Allow を選択すると、Indeed は認可コードを
redirect_uriに送信し、code、iss、stateのレスポンスフィールドを追加します。 -
redirect_uriのページからcodeパラメーターを取得します。例:
GET http://www.acerecruitersllc.com/oauth/indeed?code=rXZSMNyYQHQ&state=employer1234&iss=https%3A%2F%2Fsecure.indeed.com
OAuth認証情報を取得する
-
IndeedユーザーアカウントでPartner Consoleにログインします。
-
ダッシュボードで、アプリリストから自社のアプリを選択します。
アプリ詳細ページの認証情報タブに、OAuth認証情報(クライアントIDとクライアントシー クレット)が表示されます。
3-leggedアクセストークンを取得する
アクセストークンの有効期間は1時間です。アクセストークンを更新するには、3-leggedアクセストークンを更新するをご覧ください。
アクセストークンを取得するには、AcceptおよびContent-Typeリクエストヘッダーとリクエストボディパラメーターを指定して、https://apis.indeed.com/oauth/v2/tokensエンドポイントにPOSTリクエストを送信します。
curl -L -X POST 'https://apis.indeed.com/oauth/v2/tokens' \ -H 'Accept: application/json' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'grant_type=authorization_code' \ -d 'client_id=<client_id>' \ -d 'client_secret=<client_secret>' \ -d 'code=<authorization_code>' \ -d 'code_verifier=<code_verifier>' \ -d 'redirect_uri=http://www.acerecruitersllc.com/oauth/indeed'リクエストヘッダーは次のとおりです。
oauth/v2/tokensのリクエストボディパラメーターは次のとおりです。
| リクエストボディパラメーター | 必須 | 値 |
|---|---|---|
grant_type | ✔ | authorization_code |
client_id | ✔ | クライアントID。 |
client_secret | ✔ | クライアントシークレット。 |
scope | 条件付き | アプリに権限を付与するスコープ。 |
code | ✔ | 認可コードです。 |
code_verifier | PKCE を使用する場合は ✔ | code_challenge を生成する code verifier です。confidential client は code_challenge を使用してください。RFC 7636: Proof Key for Code Exchange by OAuth Public Clients で定義されているとおり、code verifier から OAuth PKCE code challenge を生成します。 |
redirect_uri | ✔ | URLエンコードされたリダイレクトURL。 認可コード取得時に指定したリダイレクトURLと一致している必要があります。 |
{ "access_token": "<access_token>", "convid": "1eis1tplg01fe802", "refresh_token": "<refresh_token>", "scope": "offline_access email", "token_type": "Bearer", "expires_in": 3600}3-leggedアクセストークンを更新する
アクセストークンを更新するには、Accept および Content-Type リクエストヘッダーとリクエストボディパラメーターを指定して、https://apis.indeed.com/oauth/v2/tokens に POST リクエストを送信します。
curl -L -X POST 'https://apis.indeed.com/oauth/v2/tokens' \ -H 'Accept: application/json' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'grant_type=refresh_token' \ -d 'client_id=<client_id>' \ -d 'client_secret=<client_secret>' \ -d 'refresh_token=<refresh_token>' リクエストヘッダーは次のとおりです。
oauth/v2/tokensのリクエストボディパラメーターは次のとおりです。
| リクエストボディパラメーター | 必須 | 値 |
|---|---|---|
grant_type | ✔ | refresh_token |
client_id | ✔ | クライアントID。 |
client_secret | ✔ | クライアントシークレット。 |
refresh_token | ✔ | リフレッシュトークン。 |
{ "access_token": "<access_token>", "id_token": "<id_token>", "refresh_token": "<refresh_token>", "convid": "1c1a1s8540kkt89p", "scope": "email offline_access", "token_type": "Bearer", "expires_in": 3600}Indeed APIを呼び出す
Indeed GraphQL APIを呼び出すには、以下のヘッダーとGraphQLクエリまたはミューテーションを指定してhttps://apis.indeed.com/graphqlにPOSTリク エストを送信します。
curl -L 'https://apis.indeed.com/graphql' \ -H 'Authorization: Bearer <access_token>' \ -H 'Content-Type: application/json' \ -d '{"query":"query {\n jobSearch(\n location: { radius: 5, radiusUnit: MILES, where: \"Austin\" }\n what: \"Nurse\"\n limit: 5\n ) {\n results {\n job {\n title\n sourceEmployerName\n }\n }\n }\n}","variables":{}}'リクエストヘッダー:
| ヘッダー | 値 | 説明 |
|---|---|---|
|
| このヘッダーを使用してサーバーで認証し、保護されたリソースにアクセスします。 このヘッダーで
アクセストークンを取得する、Authorization header、およびBasic authentication schemeをご覧ください。 |
|
| リソースのメディアタイプです。 Content-Type ヘッダーをご覧ください。 |
-dパラ メーターでGraphQLクエリを指定します。
query { jobSearch(location: { radius: 5, radiusUnit: MILES, where: "Austin" } what: "Nurse" limit: 5) { results { job { title sourceEmployerName } } }}{ "errors": [{ "message": "The client does not have access to the 'job-retrieval-service' service.", "extensions": { "code": "INTERNAL_SERVER_ERROR" } }], "data": null}雇用主を表すアクセストークンを取得する
一部の Indeed API では、雇用主または広告主を表すアクセストークンが必要です。
ユーザーには、次のいずれかの画面を表示できます。
どちらの画面でも、ユーザーは自分のアカウントに関連付けられた雇用主の一覧から雇用主を選択します。
その後、その雇用主のアクセストークンを取得 します。
各アクセストークンは 1 つの雇用主を表します。雇用主を切り替えるには、新しいアクセストークンを取得します。
Indeedの雇用主選択画面を表示する
-
Indeed の雇用主選択画面を表示する認可リンクを取得するには、
prompt=select_employerとscope=employer_accessクエリパラメーターを指定して、https://secure.indeed.com/oauth/v2/authorizeエンドポイントを呼び出します。この呼び出しには、
prompt=select_employerとscope=employer_accessの両方のクエリパラメーターが含まれます。https://secure.indeed.com/oauth/v2/authorize?client_id=<client_id>&redirect_uri=https%3A%2F%2Fexample.com%2Foauth&response_type=code&state=random&scope=email+offline_access+employer_access&prompt=select_employerこの認可リンクにより、次の画面が表示されます。
Indeedが提供する画面 画面 説明 認証
ユーザーがIndeedからログアウトしている場合に表示されます。
OAuth同意
employer_accessスコープなど、OAuthアプリがリクエストするスコープに対してユーザーが同意を付与できます。Indeed雇用主選択
ユーザーアカウントに関連付けられた雇用主のリストから、ユーザーが雇用主を選択できます。
ユーザーに表示される OAuth 同意画面は、Partner Console で確認できます。
-
ユーザーが雇用主を選択すると、Indeed は雇用主 ID を redirect URI に追加します。
https://example.com/oauth/callback?state=random&employer=6d2f02224e30d401810b1726eb246d8d&code=e_IEr5UlBys&iss=https%3A%2F%2Fsecure.indeed.comURL には、雇用主 ID を保持する
employerパラメーターが含まれます。prompt=select_employerを設定していても、redirect URI にemployerパラメーターが常に含まれるとは限りません。 -
雇用主アクセストークンを取得するに進みます。
カスタム雇用主選択画面を表示する
Indeed では標準の Indeed 雇用主選択画面 を推奨しています。独自の画面を使用する場合は、次のようにします。
-
OAuth同意画面を表示するため、3-leggedアクセストークンを取得します。トークンを取得する際は、
employer_accessとoffline_accessのスコープをリクエストしてください。レスポンスは access token、ID token、refresh token を返します。
-
現在のユーザーの雇用主を一覧表示するには、JSON Web Tokens Debuggerを使用してIDトークンをデコードします。
-
ユーザーが雇用主を選択できるカスタム雇用主選択画面を作成します。
-
雇用主アクセストークンを取得します。
雇用主アクセストークンを取得する
雇用主選択画面でユーザーが選択した雇用主を表すアクセストークンを取得します。
雇用主を表すアクセストークンを取得するには、Accept および Content-Type リクエストヘッダーとリクエストボディパラメーターを指定して、https://apis.indeed.com/oauth/v2/tokens エンドポイントに POST リクエストを送信します。
curl -L -X POST 'https://apis.indeed.com/oauth/v2/tokens' \ -H 'Accept: application/json' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'grant_type=authorization_code' \ -d 'client_id=<client_id>' \ -d 'client_secret=<client_secret>' \ -d 'redirect_uri=http://localhost' \ -d 'code=<authorization_code>' \ -d 'employer=<employer_id>'リクエストヘッダーは次のとおりです。
oauth/v2/tokensのリクエストボディパラメーターは次のとおりです。
| リクエストボディパラメーター | 必須 | 値 |
|---|---|---|
grant_type | ✔ |
または:
refresh token を使用して access token を取得する場合、OAuth 同意画面は不要です。 |
client_id | ✔ | クライアントID。 |
client_secret | ✔ | クライアントシークレ ット。 |
code | 認可コードを使用してアクセストークンを取得する場合は✔ | 認可コード。 |
redirect_uri | ✔ | URLエンコードされたリダイレクトURL。 |
refresh_token | リフレッシュトークンを使用してアクセストークンを取得する場合は✔ | リフレッシュトークン。 |
employer | ✔ | 雇用主のID。ユーザーが選択した雇用主のIDを指定します。 |
レスポンスには、雇用主を表す access token が含まれます。
{ "access_token": "<access_token>", "scope": "employer_access", "token_type": "Bearer", "expires_in": 3600}アプリを登録したユーザーに関連付けられていない雇用主の access token をリクエストすると、次のエラーが返されます。
{ "error_description": "Invalid request", "error": "invalid_request"}この access token は、同意したユーザーに代わって、この雇用主に対してのみ API 呼び出しに使用してください。
refresh token を access token に交換するときにも、employer パラメーターを渡すことができます。
ユーザーが雇用主を選択しない場合、またはユーザーアカウントに関連付けられた雇用主がない場合、redirect URI には employer パラメーターが含まれません。
ユーザー情報を取得する
アプリを登録したユーザーアカウントの情報を取得するには、次のいずれかを使用します。
IDトークン
IDトークンは、Base64エンコードされたJSON Web Token(JWT)で、アクセストークンを取得すると自動的に取得できます。このトークンは、ユーザーが認証済みであることを証明します。
Indeed APIはアクセストークンを読み取りますが、サードパーティアプリはユーザーの身元を検証するためにIDトークンを読み取ります。
IDトークンには、現在のユーザーに関する情報が含まれます。id_tokenをご覧ください。
JSON Web Tokenは署名されているため、公開鍵を使ってトークンが有効であることを検証してください。
https://secure.indeed.com/.well-known/keysIDトークンについて詳しくは、OpenID Connect Core 1.0 incorporating errata set 1仕様のID Tokenをご覧ください。
-
IDトークンに
emailとemail_verifiedフィールドを含めるため、アプリはemailスコープを取得する必要があります。 -
アクセストークンを取得するには、
AcceptおよびContent-Typeリクエストヘッダーとリクエストボディパラメーターを指定して、https://apis.indeed.com/oauth/v2/tokensエンドポイントにPOSTリクエストを送信します。curl -L -X POST 'https://apis.indeed.com/oauth/v2/tokens' \-H 'Accept: application/json' \-H 'Content-Type: application/x-www-form-urlencoded' \-d 'grant_type=authorization_code' \-d 'client_id=<client_id>' \-d 'client_secret=<client_secret>' \-d 'redirect_uri=http://localhost' \-d 'code=<authorization_code>'リクエストヘッダーは次のとおりです。
oauth/v2/tokensのリクエストボディパラメーターは次のとおりです。oauth/v2/tokensのリクエストボディパラメーター リクエストボディパラメーター 必須 値 grant_type✔ authorization_codeまたは:
refresh_tokenリフレッシュトークンを使用してアクセストークンを取得する場合、OAuth同意画面は不要です。
client_id✔ クライアントID。
client_secret✔ クライアントシークレット。
code認可コードを使用してアクセストークンを取得する場合は✔ 認可コード。 redirect_uri✔ URLエンコードされたリダイレクトURL。 refresh_tokenリフレッシュトークンを使用してアクセストークンを取得する場合は✔ リフレッシュトークン。 employer✔ 雇用主ID。ユーザーが選択した雇用主のIDを指定します。 JSONレスポンスには、
id_tokenフィールドが含まれます。{"access_token": "<access_token>","convid": "1erq23om7t5bu800","scope": "email employer_access","id_token": "<id_token>","token_type": "Bearer","expires_in": 3600} -
IDトークンの値をデコードするには、JSON Web Tokens Debuggerにコピーします。
レスポンスには、ユーザーのアカウントIDである
subフィールドが含まれます。{"sub": "d2d1962c0664d970"}レスポンスには、
emailとemail_verifiedフィールドが含まれます。{"aud": "a0c3b1092225d3e99f85d7aa3fe1e6001f9a0bb798717cbc2008e58fbda3ef16","sub": "d2d1962c0664d970","employers": [{"id": "13ef9940a7c1f0500a7e411e74178c4e","name": "Dharma Initiative"}, {"id": "6d2f02224e30d401810b1726eb246d8d","name": "Umbrella Corporation"}],"email_verified": true,"iss": "https://secure.indeed.com","exp": 1610417960,"iat": 1610414360,"email": "somebody@indeed.com"}
userinfo エンドポイント
現在のユーザーのアカウント情報を取得するには、Authorization: Bearer <access_token> ヘッダーを指定して、https://secure.indeed.com/v2/api/userinfo エンドポイントに GET リクエストを送信します。このエンドポイントはクエリパラメーターもリクエストボディも受け取りません。
たとえば、Log in with Indeed ボタンを作成するときに、このエンドポイントを呼び出してアカウント情報を取得できます。
レスポンスには、IDトークンが返すのと同じ情報が含まれます。
リクエストに成功すると、HTTPステータスコード200とレスポンスペイロードが返されます。
HTTP/1.1 200 OKContent-Type: application/json
{ "sub": "248289761001", "email": "mina.ray@myemail.world", "email_verified": true}v2/api/userinfoのレスポンスフィール ドをご覧ください。
v2/api/userinfo エンドポイントを呼び出すには:
-
emailとemail_verifiedフィールドを返すため、emailスコープをリクエストします。 -
認可コードグラントタイプで3-leggedアクセストークンを取得します。
-
Authorization: Bearer <access_token>ヘッダーを指定して、https://secure.indeed.com/v2/api/userinfoエンドポイントにGETリクエストを送信します。レスポンスには、ユーザーがOAuthアプリに付与したスコープの情報が含まれます。
-
レスポンスには、ユーザーのアカウントIDである
subフィールドが含まれます。{"sub": "d2d1962c0664d970"} -
レスポンスには、
emailとemail_verifiedフィールドが含まれます。{"sub": "a95064930d19bbc7","email": "somebody+samples@indeed.com","email_verified": true} -
レスポンスには、ユーザーアカウントの雇用主(または広告主)が一覧表示されます。
{"sub": "bc8c847009a955c9","email": "somebody+employer@indeed.com","email_verified": true,"employers": [{"id": "084a39249af95beedfb90cc5d2b8833c","name": "Dharma Initiative"},{"id": "865e08b649774436ee1f410b611fad7c","name": "Umbrella Corporation"},{"id": "4bc393648e880bc94dd6cef8efbc8486","name": "US Robotics and Mechanical Men"}]}
-
ユーザーを複数のURLに動的にリダイレクトする
認可コードグラントタイプ(3-legged OAuth)を使用するOAuthクライアントアプリを登録するとき、IndeedはOAuthアプリのセキュリティのベストプラクティスに従って、リダイレクトURLの数を5つに制限しています。
ユーザーを複数のURLに動的にリダイレクトするには:
-
認可URLに
stateパラメーターを追加します。https://secure.indeed.com/oauth/v2/authorize?client_id=6nwwcdklwgktryjw2j5fxh5t2fyneule7zg7mvw3pf9jbx3wmewzlxkdz1jxvs6b&redirect_uri=http%3A%2F%2Fwww.acerecruitersllc.com%2Foauth%2Findeed&response_type=code&scope=email+offline_access+employer_access&state=AnyValue -
Indeed は、リダイレクト URL に
code、iss、stateクエリパラメーターを返します。GET http://www.acerecruitersllc.com/oauth/indeed?code=rXZSMNyYQHQ&state=employer1234&iss=https%3A%2F%2Fsecure.indeed.com複数のプロバイダーに対して認証しない限り、
issパラメーターは無視できます。oauth/v2/authorize のレスポンスフィールドをご覧ください。
-
https://somesite.comなどの URL をstateパラメーターで渡すには、URL エンコードします。https://secure.indeed.com/oauth/v2/authorize?client_id=6nwwcdklwgktryjw2j5fxh5t2fyneule7zg7mvw3pf9jbx3wmewzlxkdz1jxvs6b&redirect_uri=http%3A%2F%2Fwww.acerecruitersllc.com%2Foauth%2Findeed&response_type=code&scope=email+offline_access+employer_access&state=https%3A%2F%2Fsomesite.com -
Indeed がユーザーをアプリにリダイレクトしたら、
stateパラメーターの値を使って、https://somesite.comなどの別の宛先にリダイレクトします。
ガイドライン
認可コードの漏洩を防ぐ
信頼できない Web サイトにユーザーをリダイレクトすると、HTTP Referer header によって OAuth 認可コードが漏洩します。この header には、リクエストを行ったページの URL が含まれます。
state パラメーターが指す Web サイトにも認可コードが漏洩する可能性があります。その Web サイトは、認可コードをログに記録する可能性が高くなります。
漏洩を防ぐには、信頼できないアプリにリダイレクトする前に、自社アプリ内の別の信頼できるページにユーザーをリダイレクトしてください。HTTP Referer header には直前の URL のみが含まれ、それ以前の URL は含まれません。
リダイレクト URI にクエリパラメーターを付加しない
現在、Indeed は redirect_uri パラメーター内のクエリパラメーターを受け付けます。
https://secure.indeed.com/oauth/v2/authorize?client_id=80f9f4bd6a34cac31daebe1a093a606ce6b34e91ae6cfa139432ae387269a529&response_type=code&state=random&scope=email+offline_access+employer_access&redirect_uri=https%3A%2F%2Fsomesite.com%3Freturn%3Dhttps%3A%2F%2Fsomeothersite.comこの例では、redirect_uri パラメーターが https://secure.indeed.com/oauth/v2/authorize URL の一部です。
redirect_uri の値は https://somesite.com?return=https://someothersite.com で、return クエリパラメーターの中に別のリダイレクト URL を埋め込んでいます。
redirect_uri のクエリパラメーターではなく、state パラメーターを使用してください。
関連項目
- 認証情報
- HTTPリクエストヘッダー
- oauth/v2/tokensエンドポイント
- v2/api/appinfoエンドポイント
- Basic認証スキーム
- oauth/v2/tokensのリクエストボディパラメーター
- OAuthエラーのトラブルシューティング
- GraphQLエラーのトラブルシューティング