mars/confluence/additions/Resource_Principal_Configuration_Guide.md

# Konfiguracja Resour```
Name: database-resource-principal-dg
Description: Dynamic group for database instances using Resource Principal

Matching Rules:
ANY {instance.compartment.id = 'ocid1.compartment.oc1..aaaaaaaar57tzot3jyasvp7fayc2bpepcugg4prujw6ctql42nruxjh5w72a'}

# Alternatywnie, dla konkretnej instancji:
ANY {instance.id = 'ocid1.instance.oc1..aaaaaaaa...'}

# Lub dla wszystkich instancji w tenancy:
ANY {instance.compartment.id = 'ocid1.tenancy.oc1..aaaaaaaa4chmgn5j6rsdsrvghtasdhmjok67jdathiiusv6kdzmokzp6ajua'}
```dla Oracle Cloud Database

## Przegląd

Resource Principal to mechanizm uwierzytelniania w Oracle Cloud Infrastructure (OCI), który pozwala instancjom compute (w tym Oracle Database) na bezpieczny dostęp do usług OCI bez konieczności przechowywania kluczy API lub haseł.

## 1. Wymagania wstępne

- Oracle Cloud Database działająca na OCI
- Uprawnienia administratora w OCI Console
- Dostęp do bazy danych jako ADMIN lub użytkownik z uprawnieniami DBMS_CLOUD

## 2. Konfiguracja w OCI Console

### 2.1 Utworzenie Dynamic Group

1. Zaloguj się do **OCI Console**
2. Przejdź do **Identity & Security** → **Dynamic Groups**
3. Kliknij **Create Dynamic Group**
4. Wypełnij formularz:

```
Name: database-resource-principal-dg
Description: Dynamic group for database instances using Resource Principal

Matching Rules:
ANY {instance.compartment.id = 'ocid1.compartment.oc1..aaaaaaaa...'}

# Alternatywnie, dla konkretnej instancji:
ANY {instance.id = 'ocid1.instance.oc1..aaaaaaaa...'}

# Lub dla wszystkich instancji w tenancy:
ANY {instance.compartment.id = tenancy.id}
```

5. Kliknij **Create**

### 2.2 Znajdowanie OCID kompartmentu lub instancji

**Dla kompartmentu:**
- Identity & Security → Compartments → [Wybierz kompartment] → OCID

**Dla instancji database:**
- Oracle Database → [Wybierz bazę] → DB Connection → OCID

### 2.3 Utworzenie IAM Policy

1. Przejdź do **Identity & Security** → **Policies**
2. Kliknij **Create Policy**
3. Wypełnij formularz:

```
Name: database-resource-principal-policy
Description: Policy allowing database instances to access Object Storage

Policy Statements:
Allow dynamic-group database-resource-principal-dg to manage objects in compartment ManagedCompartmentForPaaS
Allow dynamic-group database-resource-principal-dg to manage buckets in compartment ManagedCompartmentForPaaS  
Allow dynamic-group database-resource-principal-dg to read objectstorage-namespaces in tenancy
Allow dynamic-group database-resource-principal-dg to read autonomous-database-family in compartment ManagedCompartmentForPaaS

# Opcjonalnie, dla szerszego dostępu:
Allow dynamic-group database-resource-principal-dg to use cloud-shell in tenancy
```

4. Kliknij **Create**

## 3. Weryfikacja konfiguracji OCI

### 3.1 Sprawdzenie Dynamic Group

1. Przejdź do utworzonej Dynamic Group
2. Sprawdź czy **Matching Instances** pokazuje Twoją instancję database
3. Jeśli nie ma instancji, sprawdź reguły dopasowania

### 3.2 Test połączenia (opcjonalnie)

Jeśli masz dostęp SSH do compute instance:

```bash
# Test dostępu do metadata service
curl -H "Authorization: Bearer Oracle" \
     http://169.254.169.254/opc/v2/identity/cert.pem

# Jeśli zwraca certyfikat X.509, Resource Principal jest dostępny
```

## 4. Konfiguracja w Oracle Database

### 4.1 Uruchomienie skryptu konfiguracyjnego

Wykonaj skrypt `configure_resource_principal.sql` utworzony wcześniej:

```sql
-- Połącz się jako ADMIN
@configure_resource_principal.sql
```

### 4.2 Ręczna konfiguracja (alternatywa)

Jeśli skrypt automatyczny nie zadziała:

```sql
-- Połącz się jako ADMIN
CONNECT ADMIN/[password]@[service_name]

-- Sprawdź czy OCI$RESOURCE_PRINCIPAL jest dostępny
SELECT credential_name FROM user_credentials 
WHERE credential_name = 'OCI$RESOURCE_PRINCIPAL';

-- Jeśli nie istnieje, utwórz własny:
BEGIN
  DBMS_CLOUD.CREATE_CREDENTIAL(
    credential_name => 'OCI_RESOURCE_PRINCIPAL',
    username => '',  -- Pusty dla Resource Principal
    password => ''   -- Pusty dla Resource Principal  
  );
END;
/
```

### 4.3 Test konfiguracji

```sql
-- Test listowania obiektów w Object Storage
SELECT object_name 
FROM DBMS_CLOUD.LIST_OBJECTS(
  credential_name => 'OCI$RESOURCE_PRINCIPAL',  -- lub 'OCI_RESOURCE_PRINCIPAL'
  location_uri => 'https://objectstorage.eu-frankfurt-1.oraclecloud.com/n/frtgjxu7zl7c/'
) 
WHERE ROWNUM <= 5;
```

## 5. Konfiguracja dla schematów aplikacji

### 5.1 Nadanie uprawnień

```sql
-- Jako ADMIN, nadaj uprawnienia schematom aplikacji
GRANT EXECUTE ON DBMS_CLOUD TO ODS;
GRANT EXECUTE ON DBMS_CLOUD TO CT_MRDS;

-- Jeśli używasz własnego credential, nadaj dostęp:
-- GRANT READ ON CREDENTIAL OCI_RESOURCE_PRINCIPAL TO ODS;
```

### 5.2 Test z schematu aplikacji

```sql
-- Połącz się jako ODS
CONNECT ODS/[password]@[service_name]

-- Test wywołania
EXEC FILE_MANAGER_ODS.CREATE_EXTERNAL_TABLE('TEST_TABLE', 'https://...', 'OCI$RESOURCE_PRINCIPAL');
```

## 6. Aktualizacja kodu aplikacji

### 6.1 Aktualizacja FILE_MANAGER

Zaktualizuj kod aby użyć Resource Principal:

```sql
-- W procedurze CREATE_EXTERNAL_TABLE
-- Zmień z:
v_credential_name := 'OCI_RESOURCE_PRINCIPAL';

-- Na:
v_credential_name := 'OCI$RESOURCE_PRINCIPAL';  -- Jeśli dostępny
```

### 6.2 Konfiguracja ENV_MANAGER

Dodaj konfigurację do tabeli A_FILE_MANAGER_CONFIG:

```sql
INSERT INTO A_FILE_MANAGER_CONFIG (
  CONFIG_KEY, 
  CONFIG_VALUE, 
  DESCRIPTION
) VALUES (
  'DEFAULT_CREDENTIAL_NAME',
  'OCI$RESOURCE_PRINCIPAL',
  'Default OCI credential for Resource Principal authentication'
);
```

## 7. Rozwiązywanie problemów

### 7.1 Sprawdzenie statusu Dynamic Group

```sql
-- W SQL Developer Web lub SQLcl:
SELECT 
  DBMS_CLOUD.GET_OBJECT(
    credential_name => 'OCI$RESOURCE_PRINCIPAL',
    object_uri => 'https://objectstorage.eu-frankfurt-1.oraclecloud.com/n/frtgjxu7zl7c/b/data/o/test.txt'
  ) as content
FROM dual;
```

### 7.2 Typowe błędy

| Błąd | Przyczyna | Rozwiązanie |
|------|-----------|-------------|
| `ORA-20407: Invalid Credentials` | Dynamic Group nie zawiera instancji | Sprawdź reguły dopasowania w Dynamic Group |
| `ORA-20421: Object not found` | Brak uprawnień IAM | Sprawdź Policy dla Dynamic Group |
| `OCI$RESOURCE_PRINCIPAL not found` | Resource Principal nie skonfigurowany | Użyj własnego credential lub skonfiguruj ponownie |

### 7.3 Weryfikacja uprawnień

```sql
-- Sprawdź jakie credentials są dostępne
SELECT credential_name, username 
FROM user_credentials 
ORDER BY credential_name;

-- Sprawdź uprawnienia DBMS_CLOUD
SELECT grantee, privilege 
FROM user_tab_privs 
WHERE table_name = 'DBMS_CLOUD';
```

## 8. Zalecenia bezpieczeństwa

1. **Minimalne uprawnienia**: Nadaj tylko niezbędne uprawnienia w IAM Policy
2. **Monitoring**: Monitoruj użycie Resource Principal w OCI Audit
3. **Rotacja**: Resource Principal automatycznie rotuje certyfikaty
4. **Scope**: Ogranicz Dynamic Group do konkretnych instancji, nie całego compartment

## 9. Następne kroki

Po skonfigurowaniu Resource Principal:

1. Przetestuj wszystkie operacje FILE_MANAGER
2. Zaktualizuj dokumentację aplikacji
3. Skonfiguruj monitoring użycia Object Storage
4. Rozważ implementację dla innych schematów

## 10. Referencje

- [Oracle Cloud Infrastructure Resource Principal Documentation](https://docs.oracle.com/en-us/iaas/Content/Identity/Tasks/callingservicesfrominstances.htm)
- [DBMS_CLOUD Package Documentation](https://docs.oracle.com/en/cloud/paas/autonomous-database/adbsa/dbms-cloud-package.html)
- [Dynamic Groups Configuration](https://docs.oracle.com/en-us/iaas/Content/Identity/Tasks/managingdynamicgroups.htm)