knsugiyama blog

/home

/posts

/about

/tags

Home > Posts > SAP SuccessFactors の OData API を使えるようにする(OAuth 2.0)

SAP SuccessFactors の OData API を使えるようにする(OAuth 2.0)

  ·   3 min read

この記事は SAP Advent Calendar 2023 の 12 月 18 日分の記事として執筆しています。

はじめに

SAP SuccessFactors(以下 SF と略します) は、単体でも優れた人材管理ソリューションだとは思いますが、せっかく OData API が提供されているので、工夫次第で例えば

  • BTP に必要なデータを抽出し、他のシステムの情報と混ぜ合わせて新たな価値を見出す
  • SAC などの BI ツールにデータを提供することで、別の視点からデータを分析する

というようなことも出来るようになるでしょう。
そのための第一歩として、ローカル端末から SF の API を呼び出すところまでやってみます。

なお、この後実施する “SAML アサーションの生成” 方法は、非推奨となった /oauth/idp API を使わず、自身で生成する方法を取ります。
（当記事作成のモチベーションになった変更点です。ガッツリ使ってました）

ちなみに、今後の作業内容はすべて Help Portal に掲載されています。
最新情報や、より詳細な情報が必要な場合、そちらをご確認ください。

環境

  • SAP SuccessFactors: b2311.20231204122616
    • デモ環境を使います（この SF 環境調達が 1 番ハードルが高いかも）
  • Windows11: 23H2
  • Java: sapmachine-21.0.1

前提条件

  • SF の Manage OAuth2 Client Applications にアクセスできる権限を持っていること
  • SAP Note 3031657 にアクセスできること。この Note に添付されているツールを途中で使用します。

作業全体のシーケンス図

sequenceDiagram
    autonumber
    ローカル端末 ->> ローカル端末: 証明書作成
    ローカル端末 ->> +SF: OAuth2 クライアントアプリケーション登録
    SF ->> -ローカル端末: API Key 出力
    ローカル端末 ->> ローカル端末: SAML アサーション生成
    ローカル端末 ->> +SF: アクセストークン リクエスト
    SF ->> -ローカル端末: アクセストークン 返却
    ローカル端末 ->> +SF: API 実行
    SF ->> -ローカル端末: API 実行結果返却

作業詳細

事前準備 - OpenSSL を使用した X.509 証明書の作成

いきなりハードルが高いですが、SF の画面上で証明書を作成することも良しとはされていないため、頑張りましょう。

OpenSSL をインストール

とは言え、公式からソースファイルを落としてコンパイルしてー、だとただでさえ高いハードルがどこまでも高くなるので、別サイトで提供されているインストーラーを使わせてもらいます。

Win32/Win64 OpenSSL Installer for Windows - Shining Light Productions

開発を行うわけではないので、Light 版で OK

インストールはデフォルトでバシバシ進めれば OK。
ただし、path は通すようにしてください。

動作確認

> openssl version
OpenSSL 3.2.0 23 Nov 2023 (Library: OpenSSL 3.2.0 23 Nov 2023)

CSR（Certificate Signing Request） を作成

openssl req -nodes -x509 -sha256 -newkey rsa:2048 -keyout private.pem -out public.pem

所有者情報は以下のように聞かれるため、最低 1 つは入力してください。

Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (e.g. server FQDN or YOUR name) []:
Email Address []:

この記事通り実行した場合、以下ファイルが生成されます。

  1. private.pem
  2. public.pem

この時点の作業状況

sequenceDiagram
    autonumber
    ローカル端末 ->> ローカル端末: 証明書作成

OAuth2 クライアントアプリケーションの登録

Manage OAuth2 Client Applications にアクセス

Tools や 検索機能を使えば迷うこと無く開けるかと思います。

クライアントアプリケーション を登録

画像の通り、必要事項を入力します。

  • Application Name: 登録するアプリケーションの名称。一意にする必要あり
  • Description: 任意
  • Bind to Users: 要件に応じて設定
  • X.509 Certificate: 先の手順で作成した public.pem の内容を貼り付け - “BEGIN(END) CERTIFICATE” の行は不要

必要事項を入力し “Register” ボタンを押下すると、API Key が払い出されます。

この時点の作業状況

sequenceDiagram
    autonumber
    ローカル端末 ->> ローカル端末: 証明書作成
    ローカル端末 ->> +SF: OAuth2 クライアントアプリケーション登録
    SF ->> -ローカル端末: API Key 出力

SAML アサーション を作成する

先述の通り、 /oauth/idp API を使うのではなく、自分で用意する方法を取ります。
本来は idP(Identify Provider) に発行してもらうものですが、ここでは SAP Note 3031657 に倣って、ツールを使って自前で生成します。
作業詳細は、上記 KBA に記載されているので割愛しますが、ハマるかもしれないところだけ抜粋して記載します。

SAMLAssertion.properties の各項目

Note に添付されている SAMLAssertionGen 内のプロパティファイル更新内容は以下の通りです。

  1. tokenUrl: /oauth/token API を指定します(API Server の探し方は後述)
  2. clientId: OAuth クライアントアプリケーション登録時に生成された API Key
  3. userId: SF ユーザー ID
  4. userName: (userId がブランクだった場合の) ユーザー名
  5. privateKey: 証明書作成時に生成した private.pem の中身(BEGIN(END) PRIVATE KEY の行は不要)
API Server を見つけるには

利用中の SF 環境に対応する API Server を List から探します。

例えば、デモ環境であれば以下のいずれかが対応する API Server となります。

あとは Data Center の数字などから API Server を見つけてください。

本記事を作成するにあたって使用した環境は “pmsalesdemo8” であるため、API Server は、“apisalesdemo8” かと思われます。
(この当て方で正しいのかわからないため、断言できません。すみません。)

アサーション生成ツールを実行

Maven のセットアップと、“SAMLAssertion.properties” の更新作業まで終わった後に、

mvn compile exec:java -Dexec.args="SAMLAssertion.properties"
## Powershell の場合は mvn compile exec:java `-Dexec.args="SAMLAssertion.properties"

と実行すると、SAML アサーションが出力されます。
(イメージ画像末尾)

この時点の作業状況

sequenceDiagram
    autonumber
    ローカル端末 ->> ローカル端末: 証明書作成
    ローカル端末 ->> +SF: OAuth2 クライアントアプリケーション登録
    SF ->> -ローカル端末: API Key 出力
    ローカル端末 ->> ローカル端末: SAML アサーション生成

アクセストークンをリクエスト

ここまで取得・生成した情報でアクセストークンを取得します。API が実行出来るようになるまであとちょっと。

/oauth/token を呼び出してトークンを取得する

Postman などを使用して、トークン取得 API を呼び出します。

<API 情報>

URI https:// API Server /oauth/token

HTTP Method POST

Headers

Key Value
Content-Type application/x-www-form-urlencoded

Request Body

Key Value
company_id SF の Company ID
client_id 先の手順で登録した、OAuth クライアントアプリケーション の API Key
grant_type 固定値 “urn:ietf:params:oauth:grant-type:saml2-bearer”
assertion 先の手順で作成した SAML アサーション

正しい値で呼び出せた場合、access_token が取得できます。

この時点の作業状況

sequenceDiagram
    autonumber
    ローカル端末 ->> ローカル端末: 証明書作成
    ローカル端末 ->> +SF: OAuth2 クライアントアプリケーション登録
    SF ->> -ローカル端末: API Key 出力
    ローカル端末 ->> ローカル端末: SAML アサーション生成
    ローカル端末 ->> +SF: アクセストークン リクエスト
    SF ->> -ローカル端末: アクセストークン 返却

API を実行

ようやく、API を実行できるところまで進みました。
あとは SAP Business Accelerator Hub から、使用したい API を探しましょう。

ここでは ユーザー情報を取得 してみます。

<API 情報>

URI https:// API Server /odata/v2/User

HTTP Method GET

Headers なし

Authorization Bearer /oauth/token で取得したトークン

Query params 任意

適切に API を呼び出すことができれば、以下のようにユーザー情報を取得することが出来ます。

これにて、記事の最初に提示した作業工程全てが完了しました。

おわりに

記事にするとなかなかの長さになりますが、実際にやってみると案外すんなり進められますので、もし SF に携わる方で OAuth 2.0 や SAML に馴染みが無いなーという方はぜひやってみてください。
この記事ではローカル端末で証明書や SAML アサーションを作成していますので、そのままでは実運用に適用出来ない一方、認証ってどんな流れでなってるの？というのを理解するには自分でやってみるのが一番です。

最後になりますが、今年も SAP Advent Calendar を企画していただき、ありがとうございます。
1 年の最後に「何でもいいからとにかくブログ書こう」と思える場の提供、大変ありがたいです。

←
ObsidianとHugoでブログサイト作りました
back to top