Topik ini menjelaskan cara menggunakan protokol OpenID Connect (OIDC) untuk mengintegrasikan aplikasi kustom dengan layanan single sign-on (SSO) dari IDaaS. Ini membantu pengembang mengimplementasikan fitur SSO untuk aplikasi, meningkatkan pengalaman pengguna dan efisiensi manajemen.
Latar Belakang
IDaaS menggunakan mekanisme kode otorisasi berdasarkan protokol OIDC standar untuk mengimplementasikan SSO untuk aplikasi kustom perusahaan. Penyedia identitas sosial (IdP) seperti DingTalk dan WeChat menggunakan protokol OAuth untuk mengimplementasikan logon berbasis kode QR. Protokol OIDC yang digunakan oleh IDaaS adalah versi ditingkatkan dari protokol Open Authorization (OAuth).
Kompatibilitas dengan OAuth: Protokol OIDC 1.0 menambahkan lapisan identitas pengguna di atas protokol OAuth2.0. Oleh karena itu, protokol OIDC kompatibel dengan protokol OAuth2.0. Alur kode otorisasi OIDC mirip dengan alur kode otorisasi OAuth2.0. Perbedaannya adalah ketika alur kode otorisasi OIDC digunakan, titik akhir informasi pengguna distandarisasi, dan id-token pengguna dikembalikan dari titik akhir token.
Cara kerja alur kode otorisasi
Untuk aplikasi kustom, SSO diimplementasikan menggunakan alur kode otorisasi OIDC.
Aplikasi Anda hanya perlu berinteraksi dengan IDaaS di titik akhir otorisasi dan titik akhir token untuk menyelesaikan proses utama SSO.
Proses logon sepenuhnya dikelola oleh IDaaS. Aplikasi Anda hanya perlu menguraikan hasil logon.
Integrasi dengan SSO
Buat Aplikasi Kustom (atau Protokol OIDC)
Anda harus membuat aplikasi kustom atau aplikasi berbasis OIDC di IDaaS dan memperoleh kunci aplikasi. Jika Anda telah memperoleh kunci aplikasi, lewati langkah ini. Untuk informasi lebih lanjut, lihat Aplikasi Kustom untuk menyelesaikan pembuatan aplikasi.
Di tab General halaman Applications, Anda dapat memperoleh client_id dan client_secret. Pasangan kunci ini digunakan dalam permintaan API selanjutnya.
Jika Anda ingin mengelola atau mengganti kunci, lihat konfigurasi umum aplikasi di Konfigurasi Umum.
Kirim Permintaan ke Titik Akhir Otorisasi
Langkah-langkah berikut perlu ditangani oleh pengembang aplikasi.
Ketika pengguna mencoba mengakses aplikasi Anda, aplikasi harus menentukan apakah identitas logon pengguna tersedia.
Jika Anda perlu logon, Anda perlu mengirim permintaan otorisasi logon ke IDaaS. Anda dapat mengklik aplikasi Anda di halaman Applications, temukan tab Sign-In, dan peroleh titik akhir otorisasi aplikasi di bagian Application Settings .
Seperti yang ditunjukkan dalam contoh berikut, buat URL permintaan otorisasi lengkap berdasarkan URL titik akhir otorisasi dan inisiasi redirect 302 di browser.
{{Authorization Endpoint}}? client_id=app_***& redirect_uri=http%3A%2F%2Flocalhost%3A3000%2F***& response_type=code& scope=openid& state=525f49cc-***Parameter
Diperlukan
Contoh
Deskripsi
client_id
Ya
app_michs7r****6pye
client_id yang diperoleh pada langkah sebelumnya.
scope
Ya
openid email profile
Secara default, nilainya disetel ke openid email profile untuk aplikasi kustom. Ini menunjukkan bahwa aplikasi dapat memperoleh ID, nama pengguna, dan alamat email akun yang masuk. Jika Anda menggunakan aplikasi berbasis OIDC, administrator juga dapat memilih Telepon di halaman konfigurasi. Untuk informasi lebih lanjut tentang nilai parameter yang diizinkan aplikasi untuk memperoleh ketika scope ditentukan, lihat 3.2 Pemetaan antara nilai parameter yang dapat diakses oleh aplikasi dan scope yang ditentukan dalam topik ini.
response_type
Ya
code
Nilai parameter ini tetap sebagai code. Nilai ini menunjukkan bahwa mode kode otorisasi digunakan.
redirect_uri
Ya
http://localhost:3000/user/oauth2/aliyunidaas/callback
URL redirect hasil logon yang dikembalikan oleh IDaaS ke aplikasi setelah pengguna masuk ke aplikasi. URL ini adalah alamat relay untuk aplikasi menerima parameter IDaaS dan dapat menerima kode otorisasi
code.state
Tidak
525f49cc-87c4-4655-b79c-4c4f971b1ad1
String acak yang dibuat oleh aplikasi. Kami merekomendasikan Anda menyetel string dengan panjang lebih dari 32 karakter. Nilai state dikembalikan ke aplikasi di langkah selanjutnya. Aplikasi memverifikasi apakah nilai state sama dengan nilai awal yang dikirim aplikasi ke titik akhir otorisasi. Ini memastikan permintaan berasal dari sesi yang sama untuk mencegah kerentanan keamanan Cross-Site Request Forgery (XSRF). Kami merekomendasikan Anda menyetel nilai untuk parameter ini.
Logon Mandiri
Jika permintaan yang dikirim ke titik akhir otorisasi berhasil, Anda akan dialihkan ke halaman logon IDaaS.
Anda dapat menyelesaikan autentikasi melalui metode logon apa pun yang dikonfigurasi. IDaaS menyediakan berbagai kemampuan logon dengan tingkat keamanan berbeda, termasuk logon kode QR DingTalk dan logon SMS. Untuk informasi lebih lanjut, lihat Konfigurasi Umum.
Setelah logon berhasil, browser akan melakukan redirect 302 kembali ke redirect_uri yang ditentukan oleh aplikasi, dengan parameter code dan state di parameter URL.
Contoh:
{{redirect_uri}}? code=CO***& state=525f49cc-***Parameter
Contoh
Deskripsi
code
COE59pkCTm4A9nmowJUsfsfarGEaiShj3TuDc7NCzLCYu9
Kode otorisasi. Aplikasi menggunakan kode otorisasi dalam permintaan yang dikirim ke IDaaS untuk token akses.
state
525f49cc-87c4-4655-b79c-4c4f971b1ad1
Pastikan bahwa nilai
stateyang diterima aplikasi sama dengan nilai awal yang dikirim aplikasi ke titik akhir otorisasi.Kirim Permintaan ke Titik Akhir Token
Setelah aplikasi menerima kode otorisasi pada langkah sebelumnya, aplikasi tersebut menggunakan kode otorisasi untuk mengirim permintaan POST ke titik akhir token.
Mirip dengan titik akhir otorisasi yang disebutkan di atas, Anda dapat mengklik aplikasi Anda di halaman Applications, temukan tab Sign-In, dan peroleh titik akhir token di bagian Application Settings .
Permintaan sampel:
POST /v2/<instance_id>/<app_id>/oauth2/token HTTP/1.0 Host: eiam-api-cn-hangzhou.aliyuncs.com Content-Type: application/x-www-form-urlencoded grant_type=authorization_code &code=n0esc3N*****5acc3f0ogp4 &client_id=s6BhdR*****kqt3 &client_secret=7Fjfp0ZBr1*****KtDRbnfVdmIw &redirect_uri=http%3A%2F%2Fwww.example.com%2Fsso%2FcallbackRespon sampel:
{ "token_type": "Bearer", "access_token": "ATM4SoVDqWgUq***********wk3ZS5mtn6fcSp8NH8", "expires_in": 1200, "expires_at": 1644843164, "id_token": "eyJraWQiOiJLRVkyV************gRIadj-frOIRFChA" }Pada titik ini, pengguna Anda telah berhasil menyelesaikan logon. Anda dapat memilih salah satu dari dua metode berikut untuk lebih memperoleh informasi identitas logon saat ini dan membuat status logon sisi aplikasi:
Gunakan id_token dalam hasil respon, dan setelah verifikasi, langsung peroleh identitas pengguna.
Gunakan access_token dalam hasil respon untuk memanggil titik akhir pengguna IDaaS guna memperoleh informasi pengguna yang sedang masuk.
Silakan merujuk ke bagian berikut untuk metode spesifik.
PentingRentang data pengguna yang dapat diperoleh ditentukan oleh parameter scope dalam permintaan titik akhir otorisasi pada langkah pertama.
Penguraian id_token secara Programatik
id_tokenadalah token bertanda yang berisi informasi identitas (dalam format JWT). id_token yang dikeluarkan oleh IDaaS berisi data pengguna yang terlihat dalam teks biasa ketika didekode, bersama dengan Tanda Tangan.Untuk membantu Anda memahami, Anda dapat menempelkan konten
id_tokenlengkap ke Situs dekode JWT untuk melihat isinya.Kode sampel berikut memberikan contoh:
{ "kid": "KEY2Ty1qL6u21NGKmccv3jwfd2ndmgtQPnag", "alg": "RS256" }.{ "sub": "user_uyvefotjn7kpbejfmxoos3rtmm", "jti": "jwt_aaaac7xyhclac6aqkgtjaxsthw5yotn5d77pmki", "iss": "https://pre-eiam-api-cn-hangzhou.aliyun-inc.com/v2/********/oidc", "iat": 1644841965, "nbf": 1644841965, "exp": 1644842265, "aud": "app_mhylgo3iairjqjdx5eop6uaf34", "at_hash": "XHEaGpMooM9zvQXaMzCNEA", "name": "testuser", "preferred_username": "testuser", }.[Signature]Sebelum menggunakan isi untuk logon aplikasi, Anda perlu memverifikasi [Signature] untuk memastikan bahwa token dikeluarkan oleh IDaaS dan bukan oleh pihak ketiga mana pun, untuk memastikan keamanan logon. Langkah keamanan ini wajib.
Peroleh Kunci Publik Verifikasi Tanda Tangan
Sebelum melakukan verifikasi tanda tangan, Anda perlu terlebih dahulu memperoleh titik akhir kunci publik verifikasi tanda tangan yang diterbitkan oleh IDaaS.
Klik aplikasi Anda di halaman Applications, temukan tab Sign-In, dan peroleh titik akhir kunci publik di bagian Application Settings .
Aplikasi dapat memperoleh informasi kunci publik saat ini dengan mengakses titik akhir ini. Anda juga dapat membuka alamat ini langsung di browser untuk menampilkan informasi kunci publik.
Lihat contoh berikut:
{ "keys": [ { "kty": "RSA", "e": "AQAB", "use": "sig", "kid": "KEYkYnc55G********CTvT7So44RGDYdbfs", "n": "pXmYkIpy1vaNjTMclU86BQjfmDhjlqMAX8ySVvh9gO-nae4ayvG_*********-v4gP27T7u6bUy0GXTlh3eKE0v1LYB81nfqjF2uazlPwPR5yYOhhWcK-gMNByLfE3CnkDc1YGwA3dZmIz-ZjOCKy8xLaBuqjrvwn5tpMpAoYEEaH4jIm7unTdhbKEKspNR-UXKD8q9RppMh5Tn2sB6oPHlQANudJDgqSwEOevIrdmHU0Zqxrb9cscGH9hH0QjmYEu72yI8BVeliPo3jK6JIoqCIcj5K_t8BJlFQ9QLJ8_o9tmd3BFv5_LVsh4BKGw" } ] }Sekarang Anda dapat menyelesaikan verifikasi tanda tangan dan memperoleh isi dalam
id_token.Verifikasi Tanda Tangan dan Logon
Anda dapat menemukan alat bahasa yang sesuai di Daftar pustaka resmi JWT dan gunakan alat tersebut dalam kode Anda untuk memverifikasi dan mengurai
id_token.Contoh berikut menggunakan pustaka Java: org.bitbucket.b_c:jose4j.
Pertama, tambahkan dependensi Maven yang sesuai:
<dependency> <groupId>org.bitbucket.b_c</groupId> <artifactId>jose4j</artifactId> <version>0.7.12</version> </dependency>Kode berikut memberikan contoh:
import org.jose4j.jwk.JsonWebKey; import org.jose4j.jwk.JsonWebKeySet; import org.jose4j.jwt.JwtClaims; import org.jose4j.jwt.consumer.JwtConsumer; import org.jose4j.jwt.consumer.JwtConsumerBuilder; public class IdTokenTest { public static void main(String[] args) throws Exception { // Pengenal Penerbit EIAM (URL penerbit OIDC) String issuer = "https://eiam-api-cn-hangzhou.aliyuncs.com/v2/idaas_padyrlux3mphrlsex4uonyqhxu/**********/oidc"; // Pengenal unik aplikasi saat ini (diperoleh dari EIAM) String appId = "app_mkif4*****pxpzbasqmu"; // Silakan atur kunci publik aplikasi untuk penguraian sebagai berikut (format JSON, digunakan untuk memverifikasi tanda tangan JWT) String jwkJson = "{\n" + " \"keys\": [\n" + " {\n" + " \"kty\": \"RSA\",\n" + " \"e\": \"AQAB\",\n" + " \"use\": \"sig\",\n" + " \"kid\": \"KEY2H82C2at57itnW4onT3p1ySjwH4nirjCk\",\n" + " \"n\": \"w7Jl3fAUJp_9GuxV*****QsOA4lnXR5OD4kF4QbIeBiDiH8_MThrFi9k2MB6YMkSzf5JfIkpAS3JCqZ7k6Wooydp4pzaZNZAk3SGzdsa022RmAT" + "-Iayi4Yj6J9tSdTQCjwh2XkzzsIxA_Hla8rWiQ8Vhw1" + "-7QArgObfe67nSR7LxD55MFLxk9FU0*****RlGhrQGE_0LUuGWtCJG1r1e6aKquyswfxxAr3Rvj8QGIeJrG0R1Pv8m8d1_5OdULhB7149VqjM6D98WFjab0U2SNv0UlREZXTcS4p-2QNm_1egYRRpJEY_00FZqNSYsmErMGepYhO_61KoGqd8cphWQ\"\n" + " }\n" + " ]\n" + "}"; String jwt = "eyJraWQiOiJLRVkySDgyQzJhdD*****uaXJqQ2kiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2Vy*****lmNjRjZjR3amFrbnBieGpjd3V1IiwianRpIjoiand0X2FhYWFkYWllYTc2eWg1cW0zcm11bnoyeGg0eHd5aTJzZHBoNjR6aSIsImlzcyI6Imh0dHBzOi8vZWlhbS1hcGktY24taGFuZ3pob3UuYWxpeXVuY3MuY29tL3YyL2lkYWFzX3BhZHlybHV4M21waHJsc2V4NHVvbnlxaHh1L2FwcF9ta2lmNGR3bHBlaDZkbnM0cHhwemJhc3FtdS9vaWRjIiwiaWF0IjoxNjUzNjMwMDQxLCJuYmYiOjE2NTM2MzAwNDEsImV4cCI6MTY1MzYzMDM0MSwiYXVkIjoiYXBwX21raWY0ZHdscGVoNmRuczRweHB6YmFzcW11IiwibmFtZSI6InRlc3QiLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJ0ZXN0IiwidXBkYXRlZF9hdCI6MTY1MzYyODU5MH0.pAsUNB8OkdpIxJMZRfLJ7Pa31tsJyl44a1jVIlvdQxwOtPULAwrFxnB0X3eQx89hUGCdvYWl9FO9o-5kT7L-RER0wJYz9YNKqrVNBnaRwINRZyeYLRVurWMMzODQz-V0ULd9raM1M_i2f_SoWFs1gPFtYh_ijUARHISi7Q3q93ZfAuY8Lq2Nq07QunmDbosvioUd5wJG7WCxW5XXZYDUQe9p5IEYd1MSvnWuTOLbg7rKn0Vm4dNYGWjz1WuoAyCsc_QxOCqpmQ_2czoqPeN-SvPJAQ2CykLk7DSnGpABw1aNrjDidLS9Beqsga9VDCth86sk_0lyTZOaORtUrfVTtQ"; //Parse JWK public key set JsonWebKeySet jsonWebKeySet = new JsonWebKeySet(jwkJson); //Create JWT validator JwtConsumer jwtConsumer = createJwtConsumer(jsonWebKeySet, issuer, appId); //Execute signature verification and parse claims JwtClaims jwtClaims = jwtConsumer.processToClaims(jwt); // Verifikasi tanda tangan selesai. Informasi pengguna yang terkandung dalam id_token dicetak. System.out.println(jwtClaims); } // Metode yang digunakan oleh alat verifikasi tanda tangan public static JwtConsumer createJwtConsumer(JsonWebKeySet jsonWebKeySet, String issuer, String appId) { // Konfigurasikan validator JWT menggunakan pola builder final JwtConsumerBuilder jwtConsumerBuilder = new JwtConsumerBuilder(); // Konfigurasi bidang yang diperlukan jwtConsumerBuilder.setExpectedIssuer(issuer); jwtConsumerBuilder.setRequireIssuedAt(); jwtConsumerBuilder.setRequireExpirationTime(); jwtConsumerBuilder.setAllowedClockSkewInSeconds(60); jwtConsumerBuilder.setExpectedAudience(appId); // Set resolver kunci publik (cocokkan JWK berdasarkan kid) jwtConsumerBuilder.setVerificationKeyResolver((jws, nestingContext) - > { // Dapatkan kid dari header JWT final String signKeyId = jws.getKeyIdHeaderValue(); // Iterasi koleksi JWK untuk menemukan kunci yang cocok for (JsonWebKey jsonWebKey: jsonWebKeySet.getJsonWebKeys()) { if (signKeyId.equals(jsonWebKey.getKeyId())) { return jsonWebKey.getKey(); } } throw new RuntimeException("Tidak dapat menemukan kunci verifikasi: " + signKeyId); }); // Bangun instance validator return jwtConsumerBuilder.build(); } }PentingSilakan ganti bagian issuer, appId, jwkJson, dan jwt dalam kode dengan informasi aktual yang Anda peroleh dari EIAM.
Output sampel:
JWT Claims Set:{sub=user_dt6kj6yf64cf4wjaknpbxjcwuu, jti=jwt_aaaadaiea76yh5qm3rmunz2xh4xwyi2sdph64zi, iss=https://eiam-api-cn-hangzhou.aliyuncs.com/v2/idaas_padyrlux3mphrlsex4uonyqhxu/app_**********/oidc, iat=1653630041, nbf=1653630041, exp=1653630341, aud=app_**********, name=test, preferred_username=test, updated_at=1653628590 }Dengan cara ini, aplikasi memperoleh informasi identitas pengguna yang masuk di IDaaS dan menggunakan informasi tersebut untuk logon.
Peroleh Informasi Pengguna melalui Titik Akhir UserInfo
Anda juga dapat memperoleh informasi pengguna dari titik akhir UserInfo.
Klik aplikasi Anda di halaman Applications, temukan tab Sign-In, dan peroleh titik akhir UserInfo di bagian Application Settings .
Permintaan informasi pengguna menggunakan standar RFC6750. Contoh permintaan:
GET /v2/<instance_id>/<app_id>/oauth2/userinfo HTTP/1.0 Host: eiam-api-cn-hangzhou.aliyuncs.com Authorization: Bearer <AccessToken> Contoh respons: { "sub": "user_dt6kj6yf64cf4wjaknpbxjcwuu", "name": "test", "preferred_username": "test", "updated_at": 1.653.899.948 }CatatanKarakter yang dikembalikan oleh UserInfo endpoint konsisten dengan parameter dalam id_token. Ini berarti bahwa parameter yang dikonfigurasi di id_token yang diperluas juga dikembalikan dari UserInfo endpoint.
Pengaturan Lanjutan
Jika Anda memiliki pemahaman mendalam tentang protokol OIDC, Anda mungkin menggunakan konsep atau kemampuan berikut.
Titik Akhir Penemuan OIDC
issueraplikasi berbasis OIDC adalah pengenal unik penerbit token (IDaaS). Formatnya adalah sebagai berikut:https://<idaas-api-domain>/v2/<instance_id>/<application_id>/oidcTabel berikut menjelaskan parameter dalam tanda kurung sudut:
Parameter
Deskripsi
Contoh
idaas-api-domain
URL portal pengguna
https://******.aliyunidaas.com
instance_id
ID Instansi
idaas_m********r2ed22e6m
application_id
ID Aplikasi
app_m********jy6rbau
IDaaS mendukung standar OpenID Connect Discovery 1.0. Menambahkan
/.well-known/openid-configurationsetelahissuermemberi Anda alamat titik akhir penemuan OIDC untuk aplikasi.Anda dapat menemukan informasi titik akhir berikut dengan mengirim permintaan ke titik akhir penemuan. Semua titik akhir permintaan dapat diperoleh langsung dari Application Settings.
Titik Akhir
Deskripsi
authorization_endpoint
Titik akhir otorisasi
device_authorization_endpoint
Mode Perangkatmemerlukan dukungan aplikasi OIDC standar untuk fitur ini. Aplikasi kustom saat ini tidak mendukung alur logon kode perangkat.token_endpoint
Titik akhir token
revocation_endpoint
Titik akhir pencabutan token
userinfo_endpoint
Titik akhir UserInfo
jwks_uri
Titik akhir kunci publik JWK
Pemetaan antara Scope dan Izin Bidang
Tabel berikut mencantumkan informasi pengguna dalam id_token untuk aplikasi berbasis OIDC ketika scope ditentukan.
Bidang
scope
Deskripsi
sub
openid
userIdpenggunajti
openid
Token dalam format JWT. Ini adalah parameter tambahan.
iss
openid
issuerdari JWT. Ini adalah parameter tambahan.iat
openid
Waktu ketika token JWT diterbitkan. Ini adalah parameter tambahan.
nbf
openid
Waktu mulai periode validitas token JWT. Ini adalah parameter tambahan.
exp
openid
Waktu kedaluwarsa token JWT. Ini adalah parameter tambahan.
aud
openid
ClientID aplikasi. Ini adalah parameter tambahan.
at_hash
openid
Nilai hash AccessToken. Ini adalah parameter tambahan.
phone_number
phone
Nomor telepon, seperti
+86 130****5678phone_number_verified
phone
Apakah nomor telepon diverifikasi. Secara default, nomor telepon diverifikasi.
email
email
Alamat email, seperti
al***@example.comemail_verified
email
Apakah alamat email diverifikasi. Secara default, alamat email diverifikasi.
name
profile
Nama tampilan pengguna.
preferred_username
profile
usernamepenggunaupdated_at
profile
Waktu terakhir profil pengguna diperbarui.
Metode Autentikasi yang Didukung oleh Titik Akhir Token
Menurut protokol OIDC, IDaaS menyediakan fleksibilitas dan mendukung empat metode autentikasi berikut.
Bidang
token_endpoint_auth_methods_supportedyang dikembalikan di titik akhir penemuan menentukan metode autentikasi yang didukung.Nilai
Deskripsi
none
Digunakan untuk Klien Publik. Ketika melakukan autentikasi menggunakan metode autentikasi
none,grant_typetidak bolehclient_credentialsclient_secret_basic
Metode autentikasi ini diimplementasikan sesuai RFC 6749 - The OAuth 2.0 Authorization Framework.
client_secret_post
Metode autentikasi ini diimplementasikan sesuai RFC 6749 - The OAuth 2.0 Authorization Framework.
client_secret_jwt
Metode autentikasi ini diimplementasikan sesuai OpenID Connect Core 1.0.
Setelah aplikasi menerima kode otorisasi pada langkah sebelumnya dan memverifikasi bahwa permintaan tersebut valid (memverifikasi bahwa nilai state sama dengan nilai awal yang dikirim aplikasi ke titik akhir otorisasi ketika mengirim permintaan), aplikasi tersebut menggunakan kode otorisasi untuk mengirim permintaan POST ke titik akhir token.
Sebagai contoh, menggunakan
client_secret_basic, permintaan titik akhir token sampel adalah:POST /token HTTP/1.0 Host: api.aliyunidaas.com Authorization: Basic YXBwX21pY2hzN3I0*******cHllOkNTKioqKioq grant_type=authorization_code& code=COE59pkCTm4J*******arGEaiShj7NCzLCYu9Untuk informasi lebih lanjut, lihat spesifikasi OIDC Core 1.0.
Rotasi Rahasia Klien Aplikasi
Silakan merujuk ke bagian rotasi rahasia dalam Konfigurasi Umum.