Webアプリ組み込み

このページでは、WebアプリにJINS MEME APIを組み込む方法について説明します。

認可コードフロー

JINS MEME APIのアクセスにはアクセストークンが必要です。アクセストークンはOAuth 2.0の認可コードフローに基づき取得します。アプリで認可コードフローを利用するには、アプリからサーバへのリクエスト送信と、JINSプラットフォームからアプリへのデータ受信を実行できる必要があります。認可コードフローの概要は以下の通りです。

JINSログインフローのフロー

認可コードフローに伴うステップは、以下のとおりです。

  1. ユーザーはアプリのログイン操作を実施します。
  2. アプリからJINSログインの認可URLをブラウザに送信して、ブラウザはログイン画面を開きます。
  3. ユーザーはログイン認証します。JINSプラットフォームでユーザーの資格情報が検証された後、ユーザーはアプリから要求される権限を付与することに同意します。
  4. JINSプラットフォームからアプリに、redirect_uriを介してユーザーをリダイレクトします。このとき、認可コードとstateを含むクエリ文字列もアプリに送信されます。
  5. アプリは認可コードを使ってアクセストークンを要求します。INSプラットフォームはアプリからのリクエストを検証して、アクセストークンをアプリに返します。
  6. アプリは取得したアクセストークンを使って、APIを呼び出すことができます。

認可を要求する

ユーザーを認証してアプリに権限を付与するよう要求するには、以下の認可URLに必須のクエリパラメータを付けてユーザーをリダイレクトします。ユーザーをリダイレクトするには、直接リンクを使います。

https://accounts.jins.com/jp/ja/oauth/authorize

必須のクエリパラメータをURLに含める必要があります。

パラメータタイプ必須説明
response_typeString必須“code”固定。この値を指定することにより、JINSプラットフォームから認可コードが返されます。
client_idString必須アプリID。JINS MEME DEVELOPERSでプラットフォーム「Web」を設定したアプリを登録した際に払い出されたアプリID。
redirect_uriString必須コールバックURL。認証と認可の後にユーザーがリダイレクトされるURLです。JINS MEME DEVELOPERSでアプリケーションに登録したコールバックURLと一致する必要があります。
stateString必須クロスサイトリクエストフォージェリ防止用の固有な英数字の文字列。アプリ側でランダムに生成する必要があります。
scopeString必須ユーザーが付与する権限。URLエンコードされた空白文字(%20)で区切って、複数のスコープを指定できます。詳しくは、「スコープ」を参照してください。
service_idString必須“meme”固定。
login_hintString任意ログインメールアドレス。指定されたメールアドレスがログイン画面のメールアドレスに設定されます。

scopeパラメータに指定できるスコープは以下のとおりです。URLエンコードされた空白文字(%20)で区切って、複数のスコープを指定できます。少なくとも1つのスコープを指定する必要があります。

スコープ説明
officeJINS MEME OFFICE データの参照権限です。
runJINS MEME RUN NEXT データの参照権限です。
driveJINS MEME DRIVE データの参照権限です。

認可リクエストの例

以下はクエリパラメータを含む認可URLの例です。

https://accounts.jins.com/jp/ja/oauth/authorize?response_type=code&client_id=123456789012345&redirect_uri= https://example.com/cb&state= 12345abcde&scope=office%20run%20drive&service_id=meme&login_hint=test@example.com

認証と認可のプロセス

ユーザーがJINSにログインしていない場合

ユーザーは認証のためJINSログイン画面にリダイレクトされます。ユーザーはメールアドレスとパスワードを使ってJINSにログインする必要があります。ログイン後、認可画面が表示されます。

ログイン画面

ユーザーセッションが存在し、JINSにログイン済みである場合

JINSログイン画面の代わりに認可画面が表示されます。

認可画面

認可コードを取得する

ユーザーの認証と認可が完了すると、HTTPステータスコード302および以下のクエリパラメータを含むコールバックURLが返されます。

パラメータタイプ説明
codeStringアクセストークンの取得に使用される認可コード。有効期間は10分です。また、認可コードは1回のみ利用可能です。
stateString元のリクエストの認可URLに含まれるstateパラメータ。この値が元のリクエストに含まれる値と一致することを、アプリが検証する必要があります。

以下は、レスポンスの例です。

HTTP/1.1 302 Found
Location : https://example.com/callback?code=67890fgehi&state=12345abcde

エラーレスポンス

アプリの要求する権限の付与をユーザーが拒否した場合、以下のクエリパラメータを含むコールバックURLが返されます。

パラメータタイプ必須説明
errorString必須“access_denied”固定。認可画面でキャンセルした場合に設定されます。
error_descriptionString必須エラー内容。人間が判読できるASCIIエンコードのテキストです。
stateString必須OAuth 2.0のステート値。認可リクエストにstateパラメータが含まれていた場合は必ず返されます。

以下は、エラーレスポンスの例です。

https://example.com/callback?error=access_denied&error_description=The+resource+owner+or+authorization+server+denied+the+request.&state=12345abcde

アプリの要求する権限の付与をユーザーが拒否した場合、アプリ側でエラーを適切に処理する必要があります。

アクセストークンを取得する

アクセストークンを取得するには、認可コードを指定してHTTP POSTリクエストを実行します。取得したアクセストークンで、APIを呼び出すことができます。アクセストークンは、以下のエンドポイントで発行されます。

リクエスト

POST https://apis.jins.com/meme/v1/oauth/token

リクエストヘッダー説明
Content-Typeapplication/x-www-form-urlencoded

リクエストボディ

リクエストボディの情報はform-urlencodedフォーマットで記述します。

パラメータタイプ必須説明
grant_typeString必須“authorization_code”固定。
codeString必須認可コード。JINSログイン後にコールバックURLに設定された認可コードを指定します。
redirect_uriString必須コールバックURL。認可リクエストに指定したコールバックURLを指定します。
client_idString必須アプリID。JINS MEME DEVELOPERSでプラットフォーム「Web」を設定したアプリを登録した際に払い出されたアプリID。
client_secretString必須アプリSecret。JINS MEME DEVELOPERSでプラットフォーム「Web」を設定したアプリを登録した際に払い出されたアプリSecret。

以下はアクセストークンを取得するためのHTTP POSTリクエストの例です。

curl -X POST https://apis.jins.com/meme/v1/oauth/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=authorization_code' \
-d 'code=67890fgehi' \
-d 'redirect_uri=https://example.com/cb' \
-d 'client_id=123456789012345' \
-d 'client_secret=67890123456789'

レスポンス

JINSプラットフォームがアプリからのリクエストを検証し、以下の表に示すアクセストークンなどのデータをアプリに返します。

プロパティタイプ説明
access_tokenStringアクセストークン。有効期間は30日です。
refresh_tokenString新しいアクセストークンを取得するためのトークン。有効期限はありません。
token_typeStringBearer
expires_inNumberアクセストークンの有効期限が切れるまでの秒数。
scopeStringユーザーが付与する権限。

以下は、JSONレスポンスの例です。

{
  "access_token": "47912eb18a59c28550008c725ccba1074934e00c45645a882cfe47611669c298",
  "refresh_token": "47912eb18a59c28550008c725ccba1074934e00c45645a882cfe47611669c298",
  "token_type": "bearer",
  "expires_in": 2592000,
  "scope": "office drive run"
}