Անցնել պարունակությանը

Ինչպես REST API հրապարակել X-Road-ում

Ուղեցույցը նախատեսված է Անվտանգության սերվերի (Security Server) ադմինիստրատորների համար և ներկայացնում է X-Road-ում նոր ենթահամակարգ (subsystem) ավելացնելու և գրանցելու, ինչպես նաև վերջինիս համար REST API ծառայություն կարգավորելու գործընթացը։ Ուղեցույցն ընդգրկում է ինչպես արդեն գոյություն ունեցող ենթահամակարգի օգտագործման, այնպես էլ նոր ենթահամակարգ ստեղծելու դեպքերը՝ ներառյալ հաստատման քայլերն ու սպասվող կարգավիճակի փոփոխությունները։ Այն ներկայացնում է, թե ինչպես հրապարակել REST ծառայությունը OpenAPI 3 ծառայության նկարագրությամբ, ակտիվացնել այն, կարգավորել դրա հասանելիության իրավունքները և կառավարել TLS certificate-ի հաստատումը։ Ուղեցույցի նպատակն է ավարտին հասցնել հիմնական կարգավորումները, որոնք անհրաժեշտ են ADEL-ի այլ անդամների համար ծառայությունը հասանելի դարձնելու համար։

Բովանդակություն

  1. Ավելացնել նոր ենթահամակարգ
  2. Ենթահամակարգի կարգավիճակը և անվանման վարքագիծը
  3. Կարգավորել ծառայությունը
  4. Ակտիվացնել և հաստատել ծառայությունը
  5. Վերանայել և խմբագրել
  6. TLS Certificate-ի կառավարում
  7. Մուտքի իրավունքի կարգավորում
  8. Վերբեռնել TLS Certificate (անհրաժեշտության դեպքում)
  9. Ծառայության (Service) թեստավորում (ըստ ցանկության)
  10. Ինչպե՞ս ստեղծել Service URL-ը Client Security Server-ում (օրինակ)

1. Ավելացնել նոր ենթահամակարգ (subsystem)

1․ «Clients» բաժնում գտեք այն անդամին (Member), ով հրապարակում է ծառայությունը,

2․ սեղմեք «Add subsystem» տվյալ անդամի տողում,

add-subsystem-1

3․ «Add subsystem»-ում՝ - սեղմեք «Select Subsystem» և ընտրեք այն ցանկից, եթե ենթահամակարգն առկա է գլոբալ կարգավորումներում,

add-subsystem-2

add-subsystem-3

  • մուտքագրեք «Subsystem Code» և «Subsystem Name», եթե ենթահամակարգը գոյություն չունի (երկու դեպքում էլ անհրաժեշտ է, որպեսզի «Register subsystem» նշավանդակը նշված լինի),

4․ սեղմեք «Add subsystem»,

add-subsystem-4

5․ հաստատման պատուհանում սեղմեք «Yes»` գրանցումը հաստատելու համար։

add-subsystem-5

2. Ենթահամակարգի կարգավիճակը և անվանման վարքագիծը

  • Դուք կտեղափոխվեք դեպի «Clients» էջ, որի ներքևում կհայտնվի «Subsystem added» ծանուցումը։

subsystem-status

  • Նոր ավելացված ենթահամակարգը կհայտնվի «Clients» ցանկում՝ «Registration in progress» կարգավիճակով:
  • Եթե ենթահամակարգը նոր է ստեղծվել, վերջինիս անվանումը կցուցադրվի որպես «Undefined» և կթարմացվի գրանցման ավարտից հետո։

  • Եթե ենթահամակարգն արդեն գոյություն ունի, անմիջապես կցուցադրվի ճիշտ անվանումը։

  • Գրանցման հարցումը պետք է հաստատվի Կենտրոնական սերվերում (Central Server):

  • Սա կարող է կատարվել ինքնաշխատ կամ ձեռքով՝ ըստ Կենտրոնական սերվերի կարգավորումների։
  • Եթե գործընթացն ինքնաշխատ է, կարգավիճակը սովորաբար մի քանի րոպեի ընթացքում թարմացվում է՝ դառնալով «Registered»։ Անհրաժեշտ է թարմացնել «Clients»-ը՝ կարգավիճակի փոփոխությունը տեսնելու համար։

3. Կարգավորել ծառայությունը (Service)

1․ Սեղմեք ենթահամակարգի անվանը՝ մանրամասները դիտելու համար,

configure-service-1

2․ անցեք «Services»,

  • դուք կարող եք կարգավորել ծառայությունը նույնիսկ եթե ենթահամակարգի գրանցումը դեռ չի ավարտվել,
  • X-Road-ի մյուս անդամները չեն կարող ակտիվացնել ծառայությունը մինչև գրանցումը և ծառայության կարգավորումը չավարտվեն։

configure-service-2

3․ սեղմեք «Add REST»,

configure-service-3

4․ «Add REST»-ում՝

  • ընտրեք «OpenAPI 3 Description» որպես URL-ի տեսակ,
  • մուտքագրեք OpenAPI 3 URL-ը «URL» դաշտում (օր․՝ https://d14r9k0rinox9f.cloudfront.net/yaml/x-road-stats.yaml),
  • մուտքագրեք «Service Code» (օր․՝ TestAPI),
  • սեղմեք «Add»։

configure-service-4

4. Ակտիվացնել և հաստատել ծառայությունը

  • Անվտանգության սերվերը (Security Server) ներբեռնում և վերլուծում է OpenAPI նկարագրությունը։
  • Ծառայությունն ավելացվում է «Services» ցանկում, սակայն այն լռելյայն ակտիվ չէ։
  • Այն ակտիվացնելու համար անհրաժեշտ է միացնել աջ կողմում գտնվող անջատիչը համապատասխան տողի վրա։

enable-and-verify-1

  • Կհայտնվի «Service description enabled» ծանուցումը։
  • Սեղմեք ձախ կողմում գտնվող > նշանը՝ ծառայության մանրամասները դիտելու համար։

enable-and-verify-2

  • Սեղմեք «Service Code»՝ մանրամասները դիտելու համար։

enable-and-verify-3

5. Վերանայել և խմբագրել Service URL-ը

  • Service URL-ը վերցվում է OpenAPI-ի servers.url դաշտից։
  • Այս URL-ն այն հասցեն է, որտեղ անվտանգության սերվերը փոխանցում է մուտքային հարցումները:
  • Եթե վերլուծված արժեքը սխալ է, այն կարող եք խմբագրել ձեռքով։

review-and-edit

6. TLS Certificate-ի կառավարում

Տարբեր TLS certificate-ների ստուգման կարգավորման տարբերակների մասին ավելի մանրամասն տեղեկություն հասանելի է այստեղ՝ Security Server User Guide։

  • Լռելյայն «Verify TLS certificate» տարբերակը միացված է։
  • Սա նշանակում է, որ անվտանգության սերվերը ստուգում է API-ի TLS certificate-ը։

  • Ստուգումն ակտիվացնելու համար վերբեռնեք API-ի սերտիֆիկատը «Internal servers» → «Information System TLS certificate» բաժնում։

  • Եթե նախընտրում եք չստուգել TLS certificate-ը․

    • Հանեք նշումը «Verify TLS certificate» նշավանդակում,
    • այս դեպքում անհրաժեշտ չէ վերբեռնել սերտիֆիկատը։

  • Սեղմեք «Save»՝ կարգավորումները կիրառելու համար։

tls-certificate

7. Մուտքի իրավունքի կարգավորում

Մուտքի իրավունքների սահմանման վերաբերյալ ավելի մանրամասն տեղեկատվություն հասանելի է այստեղ՝ Security Server User Guide։

1․ «Access Rights» բաժնում սեղմեք «Add subjects»,

2․ սեղմեք «Search» առանց որոնման չափանիշները մուտքագրելու, որպեսզի ցուցադրվեն բոլոր գրանցված ենթահամակարգերը,

3․ ընտրեք անհրաժեշտ client ենթահամակարգ(եր)ը և սեղմեք «Add selected»,

configure-access-1

4․ ընտրված ենթահամակարգերը այժմ երևում են «Access Rights» բաժնում։ Նրանք ունեն հասանելիություն REST API-ին պատկանող բոլոր endpoint-ներին։

configure-access-2

5․ Որպես այլընտրանք, բոլոր API endpoint-ներին հասանելիություն տրամադրելու փոխարեն հնարավոր է սահմանել մուտքի իրավունքներ endpoint-ով։ Բացեք «Endpoints» ներդիրը՝ OpenAPI նկարագրության endpoint-ների ցանկը դիտելու և դրանց համար առանձին հասանելիություն սահմանելու համար։

configure-access-3

6․ Սեղմեք «Close»՝ «Services» բաժին վերադառնալու համար։

configure-access-4

8. Վերբեռնել TLS Certificate (անհրաժեշտության դեպքում)

  • Եթե TLS ստուգումն ակտիվ է, անցեք «Internal servers»։
  • «Information System TLS certificate» բաժնում սեղմեք «Add»՝ API-ի TLS certificate-ը վերբեռնելու համար։

upload-tls-certificate

9. Ծառայության թեստավորում (ըստ ցանկության)

  • Մուտք գործեք անվտանգության սերվեր, որտեղ գրանցված է client ենթահամակարգը,
  • անցեք client ենթահամակարգի «Internal Servers»,
  • փոխեք «Connection type»-ը HTTP-ի (լռելյայն կերպով, միացման տեսակը HTTPS է)։

HTTP-ն անվտանգ չէ և այն պետք է օգտագործվի միայն թեստավորման նպատակներով։ Production միջավայրում անհրաժեշտ է օգտագործել HTTPS։

HTTPS -ի դեպքում սպառող տեղեկատվական համակարգի TLS client certificate-ը անհրաժեշտ է վերբեռնել սպառողի անվտանգության սերվերում: Այն վերբեռնվում է «Information System TLS Certificate» բաժնի client ենթահամակարգի «Internal Servers»-ում։

Միացման տեսակների վերաբերյալ ավելի մանրամասն տեղեկատվություն հասանելի է այստեղ՝ Security Server User Guide։

testing-the-service

  • Ուղարկեք թեստային հարցում client անվտանգության սերվերին։ Օրինակ՝
curl -X GET \
  -H 'X-Road-Client: TEST/GOV/1234/TestClient' \
  'http://<CLIENT_SECURITY_SERVER_HOST>:8080/r1/TEST/GOV/1234/TestService/TestAPI/instances'

Անհրաժեշտ է կիրառել միևնույն client և service նույնացուցիչները (identifier), որոնք կիրառվել են client-ի և ծառայության կարգավորման ժամանակ։

10. Ինչպե՞ս ստեղծել Service URL-ը Client Security Server-ում (օրինակ)

  • Օրինակ՝ REST API-ի ուղին (base path) է https://api.stats.x-road.global/v1, իսկ API-ը տրամադրում է /instances endpoint-ը։ Endpoint-ով հարցում ուղարկելիս՝ հարցման URL-ը կլինի՝
https://api.stats.x-road.global/v1/instances
  • Սակայն նույն endpoint-ով X-Road-ում հարցում ուղարկելիս, անհրաժեշտ է REST API-ի ուղին (base path) փոխարինել client Security Server-ի REST interface-ի URL-ով և որպես ուղու պարամետրեր (path parameters) ավելացնել X-Road service identifier-ը հետևյալ ձևաչափով՝
http://<CLIENT_SECURITY_SERVER_HOST>:8080/r1/<INSTANCE_IDENTIFIER>/<MEMBER_CLASS>/<MEMBER_CODE>/<SUBSYSTEM_CODE>/<SERVICE_CODE>/<REST_API_ENDPOINT>

  • API endpoint-ի օրինակ՝ 

    https://api.stats.x-road.global/v1/instances

  • Վերը նշված API endpoint-ը X-Road-ով հարցում ուղարկելու դեպքում դառնում է հետևյալ URL-ը, երբ ծառայության նույնացուցիչն է (service identifier)՝ TEST/GOV/1234/TestService/TestAPI՝

http://<CLIENT_SECURITY_SERVER_HOST>:8080/r1/TEST/GOV/1234/TestService/TestAPI/instances