authin-api-java

Authin Client SDK for Java

راهنمای استفاده از authin-api-java در Java

ابتدا اخرین نسخه JAR فایل منتشر شده که در قسمت releases وجود دارد را به پروژه خود اضافه کنید.

به منظور احراز هویت و احراز دسترسی کاربر، می‌بایست روال زیر به ترتیب انجام شود:

1. هدایت کاربر به آدرس سامانه احراز هویت به روش زیر:

AuthorizationCodeRequest authorizationCodeRequest = AuthorizationCodeRequest.builder()
    .baseUrl(IAM_BASE_ADDRESS)                      (1)
        .clientId(YOUR_CLIENT_ID)                   (2)
        .redirectUri(YOUR_REDIRECT_URI)             (3)
        .responseType("code")                       (4)
        .addScope("openid")                         (5)
        .addIdTokenClaim("national_code")           (6)
        .addIdTokenClaim("lastname")                (7)
        .state("some_state")                        (8)
        .build();

CompletableFuture<URI> authorizationRequestFuture = 
        authorizationCodeRequest.execute();         (9)

1. آدرس سامانه احراز هویت مثال: https://demo.authin.ir
2. client_id سامانه شما در سامانه احراز هویت (این پارامتر را از ما دریافت می‌کنید)
3. redirect_uriای که در تنظیمات سامانه شما در سامانه احراز هویت ثبت شده است. بعد از اتمام فرآیند احراز هویت، کاربر به همراه یک کد که اصطلاحا authorization code نام دارد به آدرس مذکور هدایت می‌شود. برای اطلاعات بیشتر به Redirect URIs رجوع کنید. به طور مثال اگر redirect_uri شما برابر با htt://my.domain.com/Account/ExternalLoginCallback باشد، کاربر به آدرس htt://my.domain.com/Account/ExternalLoginCallback?code=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx هدایت می‌شود. پارامتر code برای مرحله بعد لازم است.
4. طبق پروتکل، نوع جوابی که خواهان دریافت آن هستیم را معین می‌کند که در این مرحله "code" می‌باشد.
5. لیست دسترسی‌هایی که می‌خواهید بر روی توکن کاربر نوشته شود را تعیین می‌کنید.
   • خصیصه‌ی openid همواره باید درخواست داده شود.
   • اگر غیر از مورد قبل، هیچ دسترسی دیگری را درخواست ندهید، تمامی دسترسی‌های موجود کاربر بر روی توکن نوشته می‌شود.
   • اگر هر دسترسی خاصی را که مد نظر دارید درخواست دهید، فقط همان دسترسی‌ها بر روی توکن کاربر نوشته می‌شوند.
6. خصیصه‌های پروفایل کاربر را که می‌خواهید به درخواست اضافه کنید. این خصیصه بر روی id_token کاربر نوشته می‌شود.
7. همانند مورد قبل، هر خصیصه‌ای را که مد نظر دارید، می‌توانید به درخواست اضافه کنید.
8. پارامتر state این امکان را به شما می‌دهد تا وضعیت (state) قبلی سیستم خود را بازیابی کنید. این پارامتر بعد از بازهدایت کاربر به redirect_uri عینا همراه url ارسال می‌شود. برای مطالعه بیشتر به State Parameter رجوع کنید.
9. نتیجه، آدرسی است که به منظور احراز هویت کاربر، باید او را به آدرس مذکور هدایت کنید.

2. در مرحله دوم، بعد از این که کاربر احراز هویت شد و به سامانه شما هدایت شد، نیاز است تا از سامانه احراز هویت، درخواست token برای کاربر مذکور بدهید. بدین منظور به روش زیر عمل کنید:

TokenRequest tokenRequest = TokenRequest.builder()
        .baseUrl(IAM_BASE_ADDRESS)                               
        .clientId(YOUR_CLIENT_ID)                       (1)
        .clientSecret(YOUR_CLIENT_SECRET)               (2)
        .redirectUri(YOUR_REDIRECT_URI)                 (3)
        .grantType("authorization_code")                (4)
        .code(code)                                     (5)
        .build();

CompletableFuture<TokenResponse> tokenRequestFuture =
        tokenRequest.execute();                         (6)

1. client_id سامانه شما در سامانه احراز هویت (این پارامتر را از ما دریافت می‌کنید)
2. client_secret سامانه شما در سامانه احراز هویت (این پارامتر را از ما دریافت می‌کنید)
3. مقدار redirect_uri که در مرحله قبل قرار دادید. توجه کنید باید این مقدار در هر دو مرحله یکی باشند.
4. چارچوب grant type، OAuthهای مختلفی را برای کاربردهای مختلف مشخص می‌کند. یکی از آن‌ها authorization_code است که برای درخواست توکن در ازای ارائه Authorization Code مورد استفاده قرار می‌گیرد. این مقدار را در این مرحله "authorization_code" قرار دهید. برای اطلاعات بیشتر به Authorization Code Grant رجوع کنید.
5. codeای را که در زیر بخش ۳ از مرحله قبل دریافت کردید در این قسمت قرار دهید.
6. پاسخ شامل پارامترهای access_token، id_token و refresh_token است.

3. بعد از دریافت توکن لازم است تا اقدام به صحت سنجی توکن‌های دریافتی کنید. این کار دارای ۲ مرحله است:

1. مرحله اول: دریافت کلید عمومی

JwksRequest jwksRequest = JwksRequest.builder()
                .baseUrl(IAM_BASE_ADDRESS)
                .build();

CompletableFuture<Jwks> jwksRequestFuture = jwksRequest.execute();

2. مرحله دوم: صحت سنجی و تجزیه توکن

ObjectNode claims = TokenValidator.validate(
        tokenResponse.getAccessToken(), (1)
        jwks,                           (2)
        "ISSUER",                       (3)
        "AUDIENCE"                      (4)
);

1. access_token دریافتی در مرحله ۲
2. کلید عمومی دریافتی در مرحله ۱ از مراحل صحت سنجی
3. صادر کننده توکن مثال https://www.authin.ir
4. شناسه سامانه‌ای که توکن برای آن صادر شده (client_id)

• جواب دریافتی شامل فقره‌های اطلاعاتی موجود در هر توکن می‌باشد. به طور مثال scopeهایی که در مرحله ۱ درخواست داده شده‌اند در access_token هستند و یا claimهایی که در مرحله ۱ در زیر بخش‌های شماره ۶ و ۷ اضافه شده‌اند را در تجزیه id_token دریافت خواهید کرد.

توجه: به هیچ عنوان بدون صحت‌سنجی، توکن‌های دریافتی را استفاده نکنید. توکن‌ها به معنی اعتبارنامه دسترسی به سامانه شما هستند.

4. پس از اتمام فرایند احراز هویت یکی از توکن‌های دریافتی refresh_token است که سامانه شما با ارائه این توکن به سامانه احراز هویت آتین می‌تواند بدون مداخله کاربر توکن جدیدی دریافت کند. مکانیزم درخواست refresh_token بدین صورت است که در صورتی که عمر توکن فعلی کاربر به اتمام رسیده و توکن منقضی شده باشد، سامانه شما با ارائه refresh_token دریافتی، توکن جدیدی را به دست می‌آورد.بدین منظور به روش زیر عمل کنید:

RefreshTokenRequest refreshTokenRequest = RefreshTokenRequest.builder()
        .baseUrl(IAM_BASE_ADDRESS)
        .clientId(YOUR_CLIENT_ID)
        .clientSecret(YOUR_CLIENT_SECRET)
        .accessToken(tokenResponse.getAccessToken())            (1)
        .grantType("refresh_token")                             (2)
        .refreshToken(tokenResponse.getRefreshToken())          (3)
        .build();

CompletableFuture<TokenResponse> refreshTokenRequestFuture = 
        refreshTokenRequest.execute();                          (4)

1. access_token دریافتی در مرحله ۲
2. این مقدار باید برابر با refresh_token باشد
3. refresh_token دریافتی در مرحله ۲
4. جواب دریافتی شامل access_token و id_tokenهای جدید همانند پاسخ مرحله 2 خواهد بود.

- لازم به ذکر است که به هنگام اجرای فرایند خروج از سامانه شما refresh_token نیز باید پاک شود.

- فراموش نکنید که توکن‌های دریافتی در این مرحله نیز باید صحت‌سنجی شوند.

5. برای دریافت اطلاعات کاربر که درخواست آن را در مرحله ۱ در scopeها داده‌اید، به روش زیر عمل کنید:

UserInfoRequest userInfoRequest = UserInfoRequest.builder()
        .baseUrl(IAM_BASE_ADDRESS)                           
        .method(UserInfoRequest.Method.Get)             (1)
        .accessToken(tokenResponse.getAccessToken())    (2)
        .build();
CompletableFuture<UserInfoResponse> userInfoRequestFuture = userInfoRequest.execute();

1. نوع درخواست که می‌تواند GET یا POST باشد.
2. access_token دریافتی در مرحله ۲.

5. فرآیند خروج کاربر:

فرآیند خروج کاربر به دو حالت زیر می‌تواند صورت پذیرد:

• حالت اول: خروج از طریق سامانه احراز هویت مرکزی آتین
  در این حالت پس از تکمیل فرآیند خروج در سامانه احراز هویت، یک درخواست از نوع POST به آدرس backchannelLogoutUri که در تنظیمات سامانه شما مشخص شده است، به صورت زیر ارسال می‌شود. پس از دریافت درخواست و استخراج logout_token، توکن مربوطه را به روشی که در بخش 3 توضیح داده شده است، صحت‌سنجی کنید. نیاز است تا در جواب درخواست وارد شده یکی از سه status code زیر را به عنوان پاسخ برگردانید:
  • 200 در صورت موفقیت آمیز بودن خروج کاربر در سامانه شما
  • 400 در صورتی که صحت‌سنجی توکن با موفقیت صورت نگیرد
  • 501 در صورتی که به هر دلیل دیگری قادر به تکمیل فرآیند خروج کاربر در سامانه خود نشوید

curl --request POST \
     --url '<backchannel_logout_uri>' \
     --header 'content-type: application/x-www-form-urlencoded' \
     --data 'logout_token="eyJxxxxxxxxxxiJ9.eyJxxxxxxxxxxIn0.rNjxxxxxxxxxxb1E"'

• حالت دوم: خروج از طریق سامانه شما (RP-Initiated Logout)
  نیاز است به منظور خروج کاربر از سامانه احراز هویت و در نتیجه خروج از دیگر سامانه‌های مربوطه، پس از اینکه فرآیند خروج کاربر از سامانه شما انجام گرفت، کاربر را به آدرس صفحه خروج سامانه آتین هدایت کنید. این درخواست شامل پارامترهای زیر است:
• id_token_hint: یکی از ID Tokenهای دریافتی از سامانه آتین مرتبط با نشست فعلی کاربر
• post_logout_redirect_uri: آدرس صفحه‌ای در سامانه شما، که پس از اتمام فرایند خروج، کاربر به آن صفحه هدایت می‌‌شود . لازم است این آدرس در سامانه آتین تعریف شده باشد.
• state: در صورت استفاده از post_logout_redirect_uri این مقدار عینا در پاسخ به سامانه شما بازمی‌گردد.

نمونه درخواست:

https://<IAM_BASE_ADDRESS>/logout?id_token_hint=YOUR_ID_TOKEN&post_logout_redirect_uri=YOUR_POST_LOGOUT_REDIRECT_URI&state=YOUR_STATE

نمونه پاسخ:

post_logout_redirect_uri?state=YOUR_STATE

توجه: در صورتی که پارامتر id_token_hint همراه درخواست ارسال نشود، فرآیند خروج کاربر به طور کامل اجرا می‌شود اما کاربر به آدرس post_logout_redirect_uri بازهدایت نخواهد شد.