※ ユーザーアプリ開発を行う場合、まずはCompany DBへのアクセス権付与を実施します。
OAuth Method
Authentication APIはResourceに対するアクセス権の取得/削除機能を提供します。
OAuthを使ってアプリの認証リクエストを行います。
|
GET |
https://{Request Host}/v1/oauth?app_id=[value]&redirect_url=[value]&response_type=[value]&scope=[value]&state=[value] |
|---|
※{Request Host}には、通常は共有サーバー「api-hrbc-jp.porterscloud.com」が入ります。個別にサーバーを立てられる場合は、該当のサーバー名を入れてください。
Input Variables
| 必須 | Parameter | Definition |
|---|---|---|
| ● | app_id | アプリ登録時に発行されたApp IDを指定します。 |
| ● | redirect_url | アプリ登録時に指定されたRedirect URLを指定します。 response_typeにcode_directを指定した場合、redirect_urlの指定は不要です。 |
| ● | response_type | 認証のタイプを指定します。次の値を指定することができます。 尚、Resourceへのアクセスを行うには、最初に必ずcodeを使用してCompany DBへのアクセス権付与を実施しておく必要があります。 code：codeを使用した認証を行います。Webブラウザを使用しているアプリの場合、この認証方式を使用します。 code_direct：codeを使用した認証方式ですが、Webブラウザを使用せず、サーバー間で直接認証を行う場合に使用します。 remove：既に取得しているアクセス権を削除する場合に使用します。 |
| ※ | scope | response_typeにcodeまたはremoveを指定する場合は必須です。 アクセス権を取得または削除するResourceの種類を指定します。 指定できるscopeの種類については後述のScope Listを、Resourceごとに必要なScopeはAPI List、または各Resource APIページを参照してください。 複数指定する場合、カンマ区切りで指定します。 response_typeにcode_directを指定する場合は、scopeは指定しません。 |
| state | response_typeにcodeまたはremoveを指定する場合に、任意のパラメータを指定できます。 redirect_urlで指定したURLにRedirectされるときに、stateで指定した値を引き継いで取得することができます。 |
Result Values
処理が成功した場合は、codeの値が取得できます。取得したcodeを元に、Token APIを使ってAccess Tokenを取得してください。
エラーが発生した場合は、Errorの値が返ります。詳細はAuthentication and Authorization Errorを参照してください。
Codeの有効期限
Codeの有効期限は、発行後30秒です。30秒以内にAccess TokenのRequestを発行してください。
Process & Output Values
response_typeの指定内容により、ProcessとOutputが異なります。
Processの詳細については、Steps for Authenticationを確認してください。
以下は、redirect_url=http://myapplication.comとして登録している場合の例です。
| response_type | 出力形式 | 出力例 |
|---|---|---|
| code | パラメータにcodeまたはErrorを付加 |
http://myapplication.com?response_type=code&code=aaa |
| code_direct | Response BodyにXLM形式でcodeを返却 | <Authentication> <Code>aaa</Code> <Error>0</Error> <Message>Success</Message> </Authentication> |
| remove | パラメータに処理結果を付加 削除成功：remove_confirmation=0 削除失敗またはキャンセル：remove_confirmation=-1 |
http://myapplication.com?response_type=remove&remove_confirmation=0 |
Company DBへのアクセス権付与
アプリがPORTERSのResourceにアクセスするには、アクセスしようとするCompany DBへのアクセス権を事前に付与しておく必要があります。
※ ユーザーアプリ開発を行う場合、必ず、開発初期に実施します。
※ Company DBへのアクセス権付与をする場合、WEBブラウザから直接APIを呼び出し（response_type=code）、PORTERSユーザーIDでログインした後に権限付与について承諾してください。
※ 本手順を実施していない場合、または、必要なアクセス権が不足している場合、Resourceへのアクセスを要求した際にエラーが発生します。
【事前準備】
必ず、PORTERSにログインしていない状態から開始してください。
ログイン状態を確認したい場合は、Webブラウザでhttps://hrbc-jp.porterscloud.comにアクセスします。
ログイン画面以外の画面が表示される場合は、ログインしていることを示していますので、ログアウトしてください。
１）OAuth APIへアクセス
次の例では、App ID=ABC、Redirect URL=http://myapplication.comの場合で、candidate_rとuser_rの権限を付与します。
次のようなURLをWEBブラウザのアドレスバーに入力して実行します。
※{Request Host}には、通常は共有サーバー「api-hrbc-jp.porterscloud.com」が入ります。個別にサーバーを立てられる場合は、該当のサーバー名を入れてください。
https://{Request Host}/v1/oauth?response_type=code&app_id=ABC&scope=candidate_r,user_r&redirect_url=http://myapplication.com
２）PORTERSのログイン画面
表示されるログイン画面に、会社ID、ユーザーID、パスワードを入力し、PORTERSにログインします。
３）権限付与確認画面
PORTERSに正常にログインできましたら、権限付与の確認画面が表示されますので、[承諾]をクリックしてください。
４）codeをパラメータに付加して、アプリのURLをRedirectで指定して返す
処理が正常に完了しましたら、codeをパラメータに付加してアプリを呼び出します。
Access Token を取得するための code を付加して、OAuth API で指定された URL へ Redirect します。
尚、認証手順詳細については、Steps for Authenticationを確認してください。
５）Access Tokenを取得
Access Tokenを取得します。
【Company DB へのアクセス権削除】
scopeが足りていない場合はResourceへのアクセスを要求した際にエラーとなりますが、
後から足りないscopeを追加することはできません。
その場合、一度Company DBへのアクセス権を削除してから再度付与する必要がございます。
以下の手順で削除をお願い致します。
１）OAuth APIへアクセス
PORTERSにログインしていない状態で下記のようなURLをアドレスバーに入力し、実行してください。
https://{Request Host}/v1/oauth?response_type=remove&app_id=[ABC]&scope=partition_r,user_r,field_r,option_r,client_r,client_w,recruiter_r,recruiter_w,contact_r,contact_w,job_r,job_w,candidate_r,candidate_w,resume_r,resume_w,process_r,process_w,activity_r,activity_w,contract_r,contract_w,sales_r,sales_w,phase_r,phase_w,attachment_r,attachment_w,opportunity_r,opportunity_w&redirect_url=http://localhost
※AppID、RedirectURLは正しいものを確認し、入力をお願い致します。
※Scopeには権限付与したものをすべて、または不明な場合は権限付与していないもの含め上記のようにすべて指定してください。
２）PORTERSのログイン画面をResponseで返す
ログイン画面に会社ID(開発環境のもの)、ユーザーID、PWを入力し PORTERSへログイン
３）権限削除確認画面をResponseで返す
アプリへの権限削除を承諾
４）結果を示すパラメータを付加して、アプリのURLをRedirectで指定して返す
※remove_comfirmation=0が返れば成功
※すべてのResourceに対するアクセス権が削除されるとアプリはPORTERS上で
利用開始前（非利用）状態になるので、そちらでもご確認可
Scope List
oauth APIでは、次のうちの一つまたは複数のScopeを指定することができます。
| Scope | Description |
|---|---|
| partition_r | パーティション情報の読み込み権限 |
| user_r | ユーザー情報の読み込み権限 |
| field_r | 項目情報の読み込み権限 |
| option_r | 選択肢項目の読み込み権限 |
| client_r | 企業の読み込み権限 |
| client_w | 企業の書き込み権限 |
| recruiter_r | 企業担当者の読み込み権限 |
| recruiter_w | 企業担当者の書き込み権限 |
| contact_r | コンタクトの読み込み権限 |
| contact_w | コンタクトの書き込み権限 |
| job_r | JOBの読み込み権限 |
| job_w | JOBの書き込み権限 |
| candidate_r | 個人連絡先の読み込み権限 |
| candidate_w | 個人連絡先の書き込み権限 |
| resume_r | レジュメの読み込み権限 |
| resume_w | レジュメの書き込み権限 |
| process_r | 選考プロセスの読み込み権限 |
| process_w | 選考プロセスの書き込み権限 |
| activity_r | アクティビティの読み込み権限 |
| activity_w | アクティビティの書き込み権限 |
| contract_r | 契約の読み込み権限 |
| contract_w | 契約の書き込み権限 |
| sales_r | 成約（売上）の読み込み権限 |
| sales_w | 成約（売上）の書き込み権限 |
| phase_r | フェーズの読み込み権限 |
| phase_w | フェーズの書き込み権限 |
| attachment_r | 添付ファイルの読み込み権限 |
| attachment_w | 添付ファイルの書き込み権限 |
|
opportunity_r
|
商談管理の読み込み権限 |
| opportunity_w | 商談管理の書き込み権限 |